EDI XML Converter Properties
You can use the Electronic Data Exchange (EDI) XML Converter to convert EDI files to XML and vice versa.
Properties are the same for most supported EDI dialects – ATIS, EANCOM, EDIFACT, Edig@s, HIPAA, HL7, IATA Cargo-IMP, IATA PADIS, NCPDP, TRADACOMS, and X12. Some properties are dialect-specific.
TIP: DataDirect XML Converters support the Standard Exchange Format (SEF) standard, which allows you to define extensions to an EDI standard. See Handling Proprietary EDI Formats for more information.
XML Converter Name in URL
EDI
Properties for EDI XML Converters
The following table describes properties for all EDI XML Converters. Note that some properties (cexpand and hexpand, for example) are dialect-specific.
Table 6-8. Properties for All EDI XML Converters Name in URL Property Name Description atis Attempt to handle X12 as ATIS Whether or not XML Converters should scan the first 100 segments of an X12 file to determine if it is an ATIS file. If the file is an ATIS file, ATIS rules are used; otherwise, X12 rules are used. Default is no. auto Auto-fixup values where possible Automatically calculates values where possible.For X12, XML Converters counts segments and fills in hash values for CTT, SE and IEA segments.For EDIFACT, XML Converters calculates segment totals for UNE, UNT, and UNZ segments. If the UNZ segment is missing, it is created as needed.The SE or UNT segments only need to be mapped; all of their elements can be automatically populated.In any header or trailer fields containing dates or times, segments are placed into the correct format based on whether they are defined as YYMMDD or CCYYMMDD for dates, or whatever length for times. Default values are filled in if they are missing.See also count . cent Window for century cut-off If the date is given in the file with a two-digit year and the output requires a four-digit year, this value is the cutoff so that the proper century can be selected. cexpand Fully expand HL7 CE/CF/CNE/CWE element HL7 includes specialized composite elements that contain coded values, the text version of the code, and the lookup table for CE, CF, CNE, and CWE elements. If you set
cexpand=yes, XML Converters attempts to expand all of the fields in the composite element.The CNE and CWE elements also allow pulling information from tables across versions of the standard – an HL7 2.4 element could look up information from an HL7 2.5 table, for example. Each of these also has an ’alternate’ set of fields, so that codes can be included both in the native (HL7, for example) and foreign code list. chr Character repertoire override Allows XML Converters to override and alter character encodings for EDIFACT-based documents (like EANCOM and IATA PADIS).You can use one or more of the following options, connected with a "+" symbol (chr=REPLACE+FINNISH, for example):
- DEFAULT
– The encoding specified in the file is used. This option cannot be used with any others.
- EANCOM
– Support for these extra EANCOM characters to UNOA and UNOB are added: #, @, [, ], {, }, \, |, ‘, and ^.
- SYMBOL
– Forces all characters, including special characters such as element and segment separators that might otherwise be permitted, to be validated against the encoding.
- REPLACE
– Replaces any invalid characters with the character specified by the invalidproperty. An underscore ("_") is used if the invalidproperty is not specified. If REPLACE is not specified, XML Converters throws an error.
- FINNISH
– Changes the meaning of certain characters in the Finnish character set for UNOA and UNOB (and adds UNOY and UNOZ as synonyms for UNOA and UNOB respectively).
See FINNISH Character Set Overrides for more information.See Explicit Character Overrides for more information on this topic. clean Remove linefeeds and nulls Whether or not you want to remove linefeeds and nulls from EDI converted to XML and vice versa. Valid values are both (directions), fromXML, toXML, and never.See also rtrim . component Component value separator When an element is a composite element, the character that is used to separate the component elements from each other within the composite element. See Using Special Characters for Separators for information about how to specify values for this property. continued Line continuation character Character appended to the segment terminator when each segment in an EDI message is split onto a new line. This character indicates to the host system that the end of the interchange has not been reached. Appended to all segments in an interchange but the last one.Note: This property is supported for all dialects except Cargo-IMP. count Enforce segment maximum counts Whether or not you want XML Converters to enforce segment counts as they are defined in the EDI repository. Valid values are:See also auto . decimal Decimal character Symbol used for the decimal character in the converted file. Usually a period or comma. See Using Special Characters for Separators for information about how to specify values for this property. decode Where to place decoded data values Allows you to specify where to place code list value descriptions when converting EDI to XML. Valid values are:
- no – code list table values are not output as XML:
<ISA15><!--I14: Interchange Usage Indicator-->P</ISA15>
- comment – adds the description as a comment. For example,
<!--Production Data-->
in the following code:<ISA15><!--I14: Interchange Usage Indicator-->P<!--Production Data--></ISA15>
- attribute – adds the description as an attribute:
<ISA15 decode="Production Data"><!--I14: Interchange Usage Indicator-->P</ISA15>
- text – adds the code as an attribute, and the description as element value:
<ISA15 value="P">Production Data</ISA15>
Note that the valueproperty must also be set to attribute to generate this output. dialect EDI dialect The EDI dialect of the file you are converting. Valid values are: ATIS, CARGO, EANCOM, EDIFACT, EDIG@S, HIPAA, HL7, IATA, and X12.Use IATA to specify the PADIS dialect.This property is used only for schema generation. See XML Schema Generation for more information. doc Include xs:documentation Whether or not include xs:documentation comments in the XML Schema. Valid values are yes (the default) and no.This property is used only for schema generation. See XML Schema Generation for more information. eol Add linefeeds between segments on write Allows you to put each segment on its own line when converting XML to EDI. (Extra linefeeds are ignored when converting EDI to XML.) Valid values are:
- yes (the default) – the value specified in the Line separator (newline) property is used to separate each segment. The normal segment output character is also generated.
- no –linefeeds between segments are not added
- an integer between 1 and 1024 – specifies the number of columns on which to wrap a line. So, for example, eol=80 wraps the line at 80 columns. If you specify an integer, the last row is not padded out to the value you specify.
element Element separator The character used to separate elements in a segment. See Using Special Characters for Separators for information about how to specify values for this property. empty How to handle empty HL7 content Controls how XML Converters manages empty fields. Empty tokens at the first level are never written to the XML file, regardless of how this property is set.In HL7 versions prior to 2.3, empty fields were treated as present, but without a value; in HL7 version 2.3 and later, empty fields are indicated with a set of quotation marks. A missing field – that is, a field for which there is no value in the data stream – does not display quotation marks.Valid values for this property are:n HL7 2.2 and earlier – XML Converters behaves as if empty=empty.n HL7 2.3 and later – XML Converters behaves as if empty=quotes.
- empty – All empty fields, with or without quotation marks, are treated as present but empty (use for HL7 2.2 and earlier).
- quotes – If the field has quotes, it is treated as empty, that is, the data stream has a null value (’""’ is recognized as a marker for an empty field, for example); otherwise, it is treated as missing, that is, there is no value in the data stream (use for HL7 2.3 and later).
empty (cont’d) Consider the following examples for different conversion scenarios:
- HL7 to XML, empty=empty
- Empty top-level elements are not output
- Empty lower-level elements are output as as empty XML elements
- Elements containing paired double-
quotes are passed through unchanged- HL7 to XML, empty=quotes
- Empty top-level elements are not output
- Empty lower-level elements are not output
- Elements containing paired double-
quotes are output as empty XML elements- XML to HL7, empty = empty
- Empty elements are passed through as empty
- Elements containing paired double-
quotes are passed through unchanged- XML to HL7, empty = quotes
- Empty elements are passed through as
paired double-quotes
- Elements containing paired double-
quotes are passed through unchanged encoding Encoding The encoding for the input file when it is not XML; or the encoding for the output file when it is not XML. The default is utf-8. field Comment element types Creates a comment at the start of each element that includes the element’s name and number. For example,<!--I14: Interchange Usage Indicator-->
in the following code:<ISA15><!--I14: Interchange Usage Indicator-->P<!--Production Data--></ISA15>
Turn off this and Comment code list (decode
) to disable all comment generation. following Segment name/segment content separator In TRADACOMS data streams, the default character used to separate the segment name and segment contents is the equal sign (=). You can use the following= property to override the default character.. See Using Special Characters for Separators for information about how to specify values for this property. group Use message groups if provided Allows you to add grouping elements to XML when converting EDI to XML. Grouping elements can make EDI messages in the converted XML easier to access with XPath for some types of documents. Consider using this property if your EDI documents use multiple message groups.Valid values for this property are:
- yes – Wraps each message group with an extra <GROUP></GROUP> element.
- always – Wraps all the output associated with an interchange (for example, everthing from an ISA segment to its IEA segment, inclusive) in an <INTERCHANGE></INTERCHANGE> element. <GROUP></GROUP> elements are also used when group=always.
- no – Grouping elements are not added to the converted XML. This is the default.
This property can also be used when generating XML Schema. hexpand Expand HL7 hex escapes In HL7 data streams, \X is an escape sequence used to include hex data in the stream. You can use this property (hexpand=yes) to expand the hex data. If the data is binary, an exception is thrown. Valid values are yes and no. hipaa Enable HIPAA Auto-detection Whether or not XML Converters should determine if an X12 file is a HIPAA file. If the file is a HIPAA file, HIPAA rules are used; otherwise, X12 rules are used.Valid values for hipaa= are:
- yes – XML Converters determines whether the X12 file is a HIPAA file.
- no – XML Converters processes the file as an X12 document, even if it is recognized as a HIPAA document. This is the default.
- loop – same as yes, but this value also creates a nested loop structure for the converted XML and generated XML Schema which can simplify this output’s use in XML mapping tools.
The hipaa property can be used with atis. ignore Ignore specific errors Allows you to specify which, if any, errors you want to ignore during XML conversion. The syntax for this field is ignore=n1,n2,n3.... For example, ignore=3,4,47 ignores errors 3, 4, and 47.Can be used with the optproperty to allow continued processing even when the data stream is missing mandatory segments and data elements. indent Whether to indent XML output Controls whether or not the XML output will be indented. Valid values are yes, no, and blank (unspecified). inter Interactive messages Certain EDI messages have alternate batch and interactive forms, depending upon whether they are used between systems that have real-time connections. The inter=yes setting causes the interactive form to be used, if available. For example, in EDIFACT, this would cause the normal envelope of UNB/UNH/UNT/UNZ to be replaced by UIB/UIH/UIT/UIZ.This property is used only for schema generation. See XML Schema Generation for more information. invalid Invalid character replacement Used with REPLACE value for the chrproperty to specify the character that should be used to replace invalid characters. The default (if invalid is not specified) is an underscore ("_")). Valid values are:See Using Special Characters for Separators for more information about how to specify values for this property. ldate How to handle ’L’ HL7 date Controls how XML Converters manages the L value (which traditionally means "local system" in HL7) if it is passed as either a date, time, datetime, or timestamp. Valid values are: leading Ignore leading zeros on numbers Whether or not you want the XML Converter engine to ignore leading zeros on numbers.Setting ignore=yes means that leading zeros on the value in the EDI and the value in the codelist are compared without any leading zeros. So with ignore=no, "012" does not match "12"; but with ignore=yes these values do match. This applies only to codelist validation, not for handling of numbers. len Strict validation on value lengths For most EDI dialects, controls whether an element’s content is checked against the upper and lower length limits as defined by the relevant EDI specification.For Cargo-IMP, however, len= enables or disables checking the entire message length against the standard limit of 1600 characters. Because Cargo-IMP requires fixed positions of certain elements, element length checking is always performed.Valid values for len= are: long Use long element names Whether you want to use long or short element and/or segment names in your XML conversions – FTX03-TextReference or FTX03, for example. Valid values for long= are: loop-prefix Prefix GROUP_... tags with the enclosing message name Allows you to prefix the name of a GROUP_no tag with the message name it appeared in. For example, <INVOIC>…<GROUP_1> becomes
< INVOIC >…< INVOIC _GROUP_1>. This property is set to no (loop-prefix=no) by default. message Message type The type of EDI message being converted. Valid values vary based on dialect and version.This property is used only for schema generation. See XML Schema Generation for more information. newline Line separator Used when converting EDI to XML, and XML to EDI when the Add linefeeds between segments on write property (eol) is set to yes. The default is crlf. See Line Separator Values for a list of values. opt Treat all segments and elements as optional If set to yes, all mandatory segments and mandatory data elements are treated as optional. If set to no (the default), a missing mandatory segment or mandatory data element triggers an error.You can use opt=no with the ignoreproperty to ignore errors for missing mandatory segments (errors 39 and 9), missing mandatory data elements (error 4), or both. For example, opt=no and ignore=39,9 allows processing to continue even if the data stream is missing mandatory segmentsEnabling this property can be useful if your provider declines to provide segments and elements that are considered mandatory according to the EDI specification, but you are aware of what the missing values are. prefix Namespace prefix Namespace prefix to be added, with the Namespace URI, to the root element. The prefix alone is added to all elements. release Release (escape) symbol The release, or escape, character. It turns off special processing of the next character. Suppose your message uses within a text description the same character that was used to separate elements. This is the character that would be used to tell the EDI processor to treat that character as a normal character and not as the end of the text. See Using Special Characters for Separators for information about how to specify values for this property. repeat Repeat symbol The repeat symbol for EDI dialects that use it. See Using Special Characters for Separators for information about how to specify values for this property. rtrim Trim trailing delimiters Typically, most trailing delimiters are removed automatically. But in the conversion process, new trailing delimiters are sometimes created. The rtrim property controls how XML Converters manages these trailing delimiters. Valid values are:You can also use this property to add additional spaces, or padding:
- pad1 – Add spaces at the top-most level only.
- pad2 – Add spaces to the first two levels only – elements and composite elements taht don’t contain other composites.
- pad3 – Add spaces for every level of element. This value can create many empty elements (when converting to XML) and many empty delimiters (when converting to EDI).
See also clean . seg Strict segment-ordering checking Whether or not you want to check segment ordering as defined by the message. If this property is set to no, message and group definitions are ignored, resulting in the possibility that data is grouped incorrectly (<GROUP_n> tags are never emitted, for example). Valid values are yes and no; the default is yes. segment Segment separator The character you want to use for segment separators. See Using Special Characters for Separators for information about how to specify values for this property. setup Write setup segment if appropriate Used to indicate whether or not to write the file’s setup segment when writing EDI. Used only if the EDI dialect supports an optional setup segment (the EDIFACT or IATA UNA segment, for example); otherwise, it is ignored. Valid values are yes and no; the default is yes. strict Strict validation mode If strict=yes, checks that all mandatory elements are present, and ensures that no composite elements are in places where only simple elements are allowed. Also checks for extra elements at the end of segments that are not part of the specification. The default is strict=no. strip Strip C-style comments Determines whether content in the incoming EDI stream wrapped in C-style/*
and*/
comment delimiters is ignored. Default setting is off (strip=no) since it can potentially conflict with real EDI content. HL7 files used with or generated by certain systems might include this markup, for example. tbl Force error if value not in code list Generates an error if the value for an element is not in the codelist associated with that element. If this property is off (no), values are not checked for the presence of a codelist. tertiary Subcomponent (tertiary) separator The character you want to use for subcomponent separators. See Using Special Characters for Separators for information about how to specify values for this property. typ Strict datatype content checking Ensures that only characters that are appropriate for a given field are included in the value for that field. For example, this property ensures that dates are valid and numbers are well-formed. uri Namespace URI Namespace URI to be added, with the Namespace prefix, to the root element. If the prefix is set, but the URI is not, the prefix is ignored. user Extension map file The URL of the SEF file containing custom message type definitions. This property can also be used when generating XML Schema. val Enable validation When set to yes (the default), the version, release, messages and segments of the EDI file (input or output) is compared to the relevant EDI repository. If the EDI file contains a value that is not in the EDI repository, an error is thrown.If validation is disabled (val=no), processing continues even if the EDI file contains a version, release, message, or segment that is not in the repository. When processing an unknown version, release, message, or segment, some checks cannot be performed because the structure of the required data is unknown.For example, if a file is of a known version but contains an unknown segment, data type checking for that segment is not performed, but checks on the remainder of the file are performed as usual. Similarly, if a message does not exist in the EDI repository, the file is still processed, but segment order checking is not performed. value Where to place coded data values Allows you to specify where you want to place coded data values in XML output. Valid values are:See also decode. version Dialect version The version of the dialect specified by the dialectproperty. Valid values vary based on dialect.This property is used only for schema generation. See XML Schema Generation for more information.FINNISH Character Set Overrides
As described elsewhere, you can use the using the Character repertoire overrideproperty (chr) to change the meaning of certain characters for the Finnish character set for UNOA (UNOY) and UNOB (UNOZ). The following table shows which characters are changed based on the character set in use.
Explicit Character Overrides
In addition to the modifiers you can specify using the Character repertoire overrideproperty (chr), you can instruct the XML Converters to take character encodings from the URI, instead of from the EDIFACT-style UNB or UIB
001
element. If you choose to do this, you may use the encodings described in the following table:These can also be combined with other
chr=
options. For example, an EDI file might specify UNOA encoding, but with lower-case text, because the sending system sent inconsistent data. Usingchr=UNOB+REPLACE
, the data could be consumed, and any non-UNOB characters would turn into '_
' characters, allowing processing to continue.XML Converters does no character checking for UNOX; rather it depends on the native platform converter or the application to ensure that the characters are valid. This is because there are too many implementation-specific details, subsets, and proprietary and local extensions, and it is not possible to account for them all.
Using Special Characters for Separators
Most special characters or symbols cannot be entered directly into a URL – you cannot specify that the colon (:) is the element separator character by entering
converter:EDI:element=::auto=yes
, for example. Instead, you must escape special characters using the appropriate decimal or hex value. To specify a colon as a element separator character, you would useconverter:EDI:element=\u3A:auto=yes
, for example. Note that not all EDI dialects use all special characters.See Table 6-11 for a complete list of separator characters and their decimal and hex values.
Which Properties Specify Separators?
The following properties can be used to specify separators for EDI XML Converters:
Restrictions for Separator Characters
The values you set for separator properties apply only when converting XML to EDI.
You cannot use letters, numbers, or spaces for separator characters.
You must use unique values for each separator property you choose to set.
Commonly Used Separator Characters
Commonly used separator characters and their escape values (in decimal and hex) are shown in the following table.
Control Characters
You can also use non-printable control characters as separators, as shown in the following table.
EDI Processing Instructions
You can specify EDI processing instruction (PI) values in the EDI XML Converter URI as described in the following table.
Leave these values blank to assume the default values. XML Converters will generate an error if a PI and URI switch have conflicting values, or if either value conflicts with one of the values encoded in a segment for these values.
The syntax of an EDI processing instruction is "
<?
" followed by processing instruction name (edi_segment, for example), followed by a space, and then the new special character.Example
Suppose an X12 document had to be written so that the segment terminator was a carriage return, the element separator was an asterisk, and the component separator was the greater-than symbol. The actual start of the file might end up looking much like this:
<?xml version="1.0" encoding="utf-8"?> <?edi_segment \r?> <?edi_element *?> <X12> <ISA> <ISA01><!--I01: Authorization Information Qualifier-->00</ISA01> <ISA02><!--I02: Authorization Information--></ISA02> <ISA03><!--I03: Security Information Qualifier-->00</ISA03> <ISA04><!--I04: Security Information--></ISA04> <ISA05><!--I05: Interchange ID Qualifier-->01</ISA05> <ISA06><!--I06: Interchange Sender ID-->1515151515</ISA06> <ISA07><!--I05: Interchange ID Qualifier-->01</ISA07> <ISA08><!--I07: Interchange Receiver ID-->5151515151</ISA08> <ISA09><!--I08: Interchange Date-->041201<!--2004-12-01--></ISA09> <ISA10><!--I09: Interchange Time-->1217</ISA10> <ISA11><!--I65: Repetition Separator-->U</ISA11> <ISA12><!--I11: Interchange Control Version-->00403</ISA12> <ISA13><!--I12: Interchange Control Number-->000032123</ISA13> <ISA14><!--I13: Acknowledgment Requested-->0</ISA14> <ISA15><!--I14: Usage Indicator-->P</ISA15> <ISA16><!--I15: Component Element Separator-->></ISA16> </ISA> ...