Nav

X12 EDI Connector

Premium

The X12 EDI Connector lets you convert X12 messages to and from DataWeave-compatible representations using lists and maps. X12 versions 003010, 003020, 003030, 003040, 003050, 003060, 003070, 004010, 004020, 004030, 004040, 004050, 004060, 005010, 005020, 005030, 005040, 005050, and 006020 are supported with supplied schema definitions for all standard transaction sets.

Prerequisites

This document assumes that you are familiar with X12, Mule, Anypoint Connectors, Anypoint Studio, Mule flows, and Mule Global Elements.

See the Release Notes for compatibility information. A link to the release notes is listed in the See Also section of this document.

To use the X12 EDI connector in a production environment, you must have purchased a MuleSoft license for Anypoint B2B.

What’s New in this Connector

X12 EDI connector 2.x makes several changes to the configuration and handling implemented by X12 EDI Connector 1.x.

  • X12 EDI connector 1.x only supports working with transaction sets from a single version of the standard. Mule 4 X12 EDI connector 2.x supports working with transaction sets from multiple versions of the standards. The version information included in the group (GS segment) data is used to identify the standard version, and the transaction set identifier determines the particular schema.

  • Clearer configuration options are provided for standard X12 vs HIPAA usage. The formValidation parameter selects whether you’re using standard X12, HIPAA with SNIP Type 1 validation, or HIPAA with SNIP Type 2 validation (other SNIP validation types are not implemented at the connector level, but can be implemented in your application code). Only standard X12 schemas may be used when X12 is selected; only HIPAA schemas may be used when either HIPAA option is selected.

  • The default character encoding is taken from the Mule platform, but can be changed to one of the standard X12 character encodings in the configuration.

  • Identification parameters are no longer used for the read and write operations. You can configure all parameter values in the actual message data passed to the write operation.

  • X12 EDI Connector 1.x provides a validateBeforeWrite configuration option to check for any errors in data before writing to the output stream. In the X12 EDI connector 2.x this behavior is the only mode of operation and the configuration parameter is no longer supported.

To Install this Connector in Anypoint Studio 7

  1. In Anypoint Studio, click the Exchange icon in the Studio task bar.

  2. Click Login in Anypoint Exchange.

  3. Search for the connector and click Install.

  4. Follow the prompts to install the connector.

When Studio has an update, a message displays in the lower right corner, which you can click to install the update.

You must change the default Anypoint configuration to use the X12 EDI connector 2.0.0.

Anypoint Studio 7.1.0 and later may require more than the standard memory configuration to use the X12 EDI connector 4.0.0. To change the memory setting for Studio, edit the Anypoint.ini file in the Anypoint Studio installation directory and change the two lines starting with -Xms and -Xmx to:


         
      
1
2
-Xms4096m
-Xmx4096m

This sets the Anypoint Studio memory to 4 GB, which is sufficient for most usage of this connector.

To Create Schemas

Create schemas to describe your messages according to your implementation.

About the EDI Schema Language

The X12 EDI Module uses a YAML format called ESL (for EDI Schema Language) to represent EDI schemas. Basic ESLs define the structure of EDI messages in terms of structures (transaction sets, in X12 terminology), groups (loops, in X12), segments, composites, and elements. ESLs for the X12 versions 003010, 003020, 003030, 003040, 003050, 003060, 003070, 004010, 004020, 004030, 004040, 004050, 004060, 005010, 005020, 005030, 005040, 005050, and 006020 are included. A set of HIPAA variations of base X12 transaction sets are also included.

You can customize the X12 schema definitions to suit your data by defining an overlay schema. An overlay schema is a special form of ESL that allows you to modify a base schema, such as an X12 4010 850 schema, with your specific conventions. You don’t need an overlay schema if you’re using the structure defined by the standard, but most EDI exchanges modify the base definitions in an implementation convention.

You can also define your own schemas from scratch, or copy and edit a base X12 schema definition to suit your data. See the EDI Schema Language Reference for more details.

YAML uses a combination of lists and sets of key-value pairs. The order of values is not important, as long as the required items are present. Quotes (either single or double quotes) are used around values that may consist of digits but are meant to be interpreted as strings (since otherwise the YAML parser treats the values as numbers). Indentation is used to show the nesting of lists.

For readability, the ESL structures shown here define all simple key-value pairs before any lists that are part of the same definition.

To Define your Implementation Convention with an Overlay Schema

To specify a schema according to your implementation convention, you can follow this process:

  1. Create an overlay schema that imports the base schema you want to customize - for example, X12 005010 850.

  2. Customize the overall structure for segment usage, positions, groups, and counts.

  3. Customize segments, including usage and counts.

Overlay schemas are very similar in structure to a complete schema definition, but instead of providing all the details of the schema structure they only list changes. Overlay schemas specify how to use implementation conventions with a particular trading partner to extend and customizes the standard.

The following example provides the start of a sample overlay schema that modifies the basic X12 005010 850 transaction set definition. This example customizes the CUR segment and specifies that it is unused, thereby ensuring it is hidden from the mapping structures in Anypoint Studio.


          
       
1
2
3
4
5
6
7
8
9
form: X12
version: '005010'
imports: [ '/x12/005010/850.esl' ]
structures:
- idRef: '850'
  name: Purchase Order
  class: PO
  heading:
  - { idRef: 'CUR', position: '0400', usage: U }

Structure Overlay

A structure overlay details modifications to the base schema definition of an X12 transaction set. Most often these modifications take the form of marking segments or groups in the base definition as unused, but any usage or repetition count change is allowed.

The following is the form taken by a structure overlay:


          
       
1
2
3
4
5
6
7
8
9
10
- idRef: '850'
  heading:
  - { idRef: 'CUR', position: '0400', usage: U }
  - { idRef: 'PER', position: '0600', usage: U }
  - groupIdRef: 'N9_Loop'
    position: '2950'
    items:
    - { idRef: 'DTM', position: '2970', usage: U }
    - { idRef: 'PWK', position: '3050', usage: U }
    - { idRef: 'EFI', position: '3080', usage: U }

The modifications in this example specify that the CUR and PER segments of the standard 850 heading are not being used, along with the segments in the N9 loop.

The key-value pairs at the structure level are:

Key Description

idRef

The ID for the transaction set being modified.

name

The transaction set name (optional).

heading, detail, summary

List of segment and group modifications within each section of the structure. These are optional, and each is only used when there are modifications to that section.

The lists of segment modifications for the different sections of the structure (heading, detail, summary) all use the same structure. Each item in the list is either a segment reference or a group definition. Segment references are shown using a compact YAML syntax where the values for each reference are given as comma-separated key-value pairs enclosed in curly braces. The values are:

Key Description

idRef

The referenced segment ID. This is optional and verified if provided, but otherwise ignored. The position value is used to uniquely identify segments within the section.

position

The segment position within the transaction set section.

usage

Usage code, which may be M for Mandatory, O for Optional, C for Conditional, or U for Unused.

count

Maximum repetition count value, which may be a number or the special value >1 meaning any number of repeats. The count value is optional and a base definition value is used if a value is not specified.

Group overlays are shown in expanded form, with key-value pairs on separate lines. The values in a group definition are:

Key Description

groupIdRef

The referenced group ID. This key is optional and verified if provided, but otherwise ignored. The position value is used to uniquely identify a group within a section.

position

The segment position within the transaction set section.

usage

Usage code, which may be M for Mandatory, O for Optional, C for Conditional, or U for Unused.

count

Maximum repetition count value, which may be a number or the special value >1 meaning any number of repeats. The count value is optional and a base definition value is used if a value is not specified.

items

List of segments (and potentially nested loops) making up the loop.

Segment Overlays

A segment overlay again details modifications to the base schema definition. Most often these modifications take the form of marking elements or composites in the base definition as unused, but any usage or repetition count change is allowed. Here are some sample segment overlays:


          
       
1
2
3
4
5
6
7
8
9
10
segments:
- { idRef: AMT, trim: 3 }
- idRef: BEG
  items:
  - { position: 4, usage: U }
- { idRef: DTM, trim: 3 }
- idRef: ITD
  items:
  - { position: 4, usage: U }
  - { position: 6, usage: U }

The above example uses the compact form for segment modifications that only involve a truncation, while modifications that make changes to individual values are expressed in expanded form. As with all the other YAML examples, the two forms are actually equivalent and can be used interchangeably.

The key-value pairs in a segment overlay are:

Key Description

idRef

Segment identifier.

trim

Trim position in segment, meaning all values from this point on are marked as unused (optional).

items

List of individual value modifications.

The items list references values in the segment by position. The values for these references are:

Key Description

position

The value position within the segment.

name

The name of the value in the segment (optional, base definition value used if not specified).

usage

Usage code, which may be M for Mandatory, O for Optional, C for Conditional, or U for Unused.

count

Maximum repetition count value, which may be any number or the special value >1 meaning any number of repeats. The count value is optional and a base definition value is used if a value is not specified.

To Determine the X12 Schema Location

To use the connector, you need to know the locations of the schemas in your project. If you’re using out-of-the-box X12 schemas and not customizing anything, the schema location follows the /x12/{version}/{transaction set}.esl pattern. For example, if you’re using the 005010 version and the 850 transaction set, your schema location is /x12/005010/850.esl.

If you’re using one or more custom schemas, you should put these under a directory in src/main/app and refer to the location using ${app.home}. For example, if you’ve put your 850 schema (either overlay or full) under src/main/app/mypartner/850.esl, your schema location is `${app.home}/mypartner/850.esl.

The Mule Runtime automatically checks src/main/app for any locations that contain the ${app.home} value.

To Create a Mule Project in Anypoint Studio 7

After you install the connector and customize your schemas (if needed), you can start using the connector. Create separate configurations for each implementation convention.

  1. Click the Global Elements tab at the base of the canvas, and click Create.

  2. In the Choose Global Type wizard, locate and select the X12 EDI: Configuration, and click OK.

  3. Click OK to save the global connector configurations.

  4. Return to the Message Flow tab in Studio.

Set each tab in the Global Element Properties as described in the sections that follow.

About the General Tab

General tab properties

The general tab lets you configure settings for reading and writing X12 messages:

  • X12 form and validation (standard X12, HIPAA SNIP Type 1, or HIPAA SNIP Type 2).

  • Manually create or edit the list of schema definitions for the message structures to be used (which must use the same form, either X12 or HIPAA).

  • X12 character encoding, used for both send and receive messages.

  • X12 character set allowed in string data (BASIC, EXTENDED, or UNRESTRICTED).

  • String substitution character, used to replace invalid characters in string data.

  • Version identifier code suffix, specifying a value appended to the base schema version in the GS08 Version / Release / Industry Identifier Code field.

About the Identity Tab

Identity tab properties

The Identity tab lets you configure the Interchange Control Header (ISA) and Functional Group Header (GS) identifier values for you and your trading partner in the X12 EDI connector configuration. All these values are optional. If any are configured, the values are verified when reading an input message and used as the defaults when writing an output message if no value is specified in the output data.

The values that can be set are the Interchange ID qualifier and Interchange ID for your Mule application and partner, and the Application Code for Mule and partner. The Mule values specify the Receiver fields (ISA07/ISA08, GS03) in a receive message, and populate the Sender fields (ISA05/ISA06, GS02) fields in a send message.

About the Parser Tab

Parser tab properties

You can set the following options to control parser validation of receive messages if needed:

  • Enforce minimum and maximum lengths for receive values.

  • Enforce allowed character set.

  • Enforce repetition count limits for receive values.

  • Allow unknown segments in a transaction set.

  • Enforce segment order in a transaction set.

  • Allow segments marked as Unused in a transaction set.

  • Enforce segment repetition count limits in a transaction set.

Note that changing these options from their default setting of true interferes with HIPAA SNIP Type 1 and Type 2 validation of messages. Only use these options with standard X12 data, not with HIPAA.

Other parser options let you:

  • Require unique ISA Interchange Control Numbers (ISA13).

  • Enforce globally unique Group Control Numbers (GS06) for received functional groups.

  • Enforce globally unique Transaction Set Control Numbers (ST02) for received transaction sets.

  • Set the minimum number of days to store interchange, group, and transaction set numbers for checking uniqueness.

  • Include a separate AK2/AK5 (997) or AK2/IK5 (999) acknowledgment for every received transaction set (rather than using implicit acknowledgments for transaction sets without errors).

  • Generate 999 Implementation Acknowledgments, rather than the 997 Functional Acknowledgments generated by default. Note that the support for 999 Implementation Acknowledgments does not include CTX segment generation.

  • Report segment error details to sender in the generated 997/999 acknowledgments.

  • Automatically include a standard 997 or 999 schema that matches the generated acknowledgment in the configuration for received messages.

About the Writer Tab

Writer tab properties

Writer options let you specify the separator characters used when writing messages, along with:

  • Line ending written between segments, used to make the output more readable.

  • Whether to generate unique GS group control numbers across interchanges.

  • Whether to generate unique ST transaction set control numbers across groups and interchanges.

  • An implementation convention reference (ST03) value.

  • The starting interchange control number (used only when no current value is found in the object store).

  • The starting group control number (used only when no current value is found in the object store).

  • The starting transaction set control number (used only when no current value is found in the object store).

  • Whether to request interchange acknowledgments (ISA14).

  • The default interchange usage indicator (ISA15), used when no value is present in the message data.

Example: X12 Studio

The following flow can be loaded in the XML for a project.

Mapping Flow Diagram


         
      
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:ee="http://www.mulesoft.org/schema/mule/ee/core"
xmlns:x12="http://www.mulesoft.org/schema/mule/x12"
xmlns:http="http://www.mulesoft.org/schema/mule/http"
xmlns="http://www.mulesoft.org/schema/mule/core"
xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.mulesoft.org/schema/mule/core
http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/http
http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/x12
http://www.mulesoft.org/schema/mule/x12/current/mule-x12.xsd
http://www.mulesoft.org/schema/mule/ee/core
http://www.mulesoft.org/schema/mule/ee/core/current/mule-ee.xsd">
        <http:listener-config name="HTTP_Listener_config" doc:name="HTTP Listener config">
                <http:listener-connection host="localhost" port="8081" />
        </http:listener-config>
        <x12:config name="X12_EDI_Config" doc:name="X12 EDI Config">
            <x12:schemas>
                <x12:schema value="/x12/005010/850.esl"/>
            </x12:schemas>
        </x12:config>
        <flow name="x12mappingFlow">
                <http:listener doc:name="Listener" config-ref="HTTP_Listener_config" path="/x12"/>
                <x12:read doc:name="Read" config-ref="X12_EDI_Config"/>
                <ee:transform doc:name="Transform Message">
                        <ee:message >
                                <ee:set-payload ><![CDATA[%dw 2.0
output application/java
---
{
    TransactionSets: {
        v005010: {
            "850": payload.TransactionSets.v005010."850"
        }
    }
}]]></ee:set-payload>
                        </ee:message>
                </ee:transform>
                <x12:write doc:name="Write" config-ref="X12_EDI_Config"/>
        </flow>
</mule>

Configuration Options in XML

All values listed in the Studio configuration can be set directly in XML.

General parameters control both send and receive document handling (all are optional, with default values as shown):

XML Value Visual Studio Option

formValidation="X12"/"HIPAA_SNIP1"/"HIPAA_SNIP2"

Schema form and validation level, default is "X12". Schemas used in the configuration must match the form selected, either X12 or HIPAA.

schemas=list of values

List of paths for schemas to be used by connector. The paths may be either for a file system or classpath.

characterEncoding="PLATFORM"/"ASCII"/"ISO8859_1"/"IBM1047"/"UTF8"

Character encoding for messages, default is "PLATFORM", meaning the Mule platform default encoding. This character encoding is always used to both send and receive messages.

stringCharacterSet="BASIC"/"EXTENDED"/"UNRESTRICTED"

Characters allowed in string data, default is "EXTENDED". Invalid characters are replaced by the substitution character, if used, or rejected as errors if no substitution character is set or enabled for receive messages in parser options.

stringSubstitutionChar="?"

Substitution character used to replace invalid characters in string values. Default is none.

versionIdentifierSuffix="XYZ"

Version identifier code suffix for group (GS). If this value is set, it affects both send and receive message handling. On the receive side, the GS08 version code must consist of the X12 schema version (004010, 005010, etc.) followed by this suffix. If this value is not set, the receive only verifies that the GS version identifier code starts with the configured schema version. On the send side, the combination of the X12 schema version and this suffix is used as the GS08 value.

Self identification parameters optionally identify your side of the trading partner relationship:

XML Value Visual Studio Option

interchangeIdQualifierSelf="ZZ"

ID qualifier for Mule in Exchange (ISA segment). This value is used in combination with the Interchange ID value, and if one is set the other must also be set.

interchangeIdSelf="mule"

ID for Mule in Exchange (ISA segment). This value is used in combination with the Interchange ID qualifier value, and if one is set the other must also be set.

groupIdSelf="muleapp"

Application Code for Mule in a group (GS segment).

Partner identification parameters optionally identify your partner:

XML Value Visual Studio Option

interchangeIdQualifierSelf="ZZ"

ID qualifier for a partner in Exchange (ISA segment). This value is used in combination with the Interchange ID value, and if one is set the other must also be set.

interchangeIdSelf="partner"

ID for a partner in Exchange (ISA segment). This value is used in combination with the Interchange ID qualifier value, and if one is set the other must also be set.

groupIdSelf="partnerapp"

Application Code for a partner in a group (GS segment).

Parser parameters control the parser operation and the types of error conditions which cause receive transaction sets to be rejected (all are optional, with default values as shown):

XML Value Visual Studio Option

enforceLengthLimits="true"

Enforce minimum and maximum lengths for receive values.

enforceCharacterSet="true"

Enforce allowed character set.

enforceValueRepeats="true"

Enforce repetition count limits for receive values.

allowUnknownSegments="false"

Allow unknown segments in a transaction sett.

enforceSegmentOrder="true"

Enforce segment order in a transaction set.

allowUnusedSegments="false"

Allow segments marked as 'Unused' in a transaction set.

enforceSegmentRepeats="true"

Enforce segment repetition count limits in a transaction set.

requireUniqueInterchanges="true"

Require unique ISA Interchange Control Numbers (ISA13). The default behavior is to record the interchange numbers previously processed and reject any duplicate interchange numbers from the same partner (as determined by the interchange sender and receiver identification). If false, this instead allows processing of the received interchange to continue and leaves it to the application flow to track numbers and handle appropriately.

requireUniqueGroups="false"

"Enforce globally unique Group Control Numbers (GS06) for received functional groups. By default, group numbers only need to be unique with an interchange. If true, this instead requires group numbers to be unique across all interchanges received from the same partner and application (as determined by the interchange sender and receiver identification, combined with the functional group sender and receiver application codes).

requireUniqueTransactionSets="false"

Enforce globally unique Transaction Set Control Numbers (ST02) for received transaction sets. By default, transaction set control numbers only need to be unique with a particular functional group. If true, this instead requires transaction set numbers to be unique across all functional groups received from the same partner and application (as determined by the interchange sender and receiver identification, combined with the functional group sender and receiver application codes).

daysToStore="30"

Minimum number of days to store interchange, group, and transaction set numbers for checking uniqueness.

ackAllSets="false"

Include a separate AK2/AK5 (997) or AK2/IK5 (999) acknowledgment for every received transaction set. By default, only transaction sets containing errors are included in the acknowledgment, with transaction sets which aren’t included implicitly acknowledged. Changing this flag causes each received transaction set to be explicitly acknowledged.

generate999Acks="false"

Generate 999 Implementation Acknowledgments, rather than 997 Functional Acknowledgments. By default, 997 Functional Acknowledgment transaction sets are generated for each received interchange. Changing this flag causes 999 Implementation Acknowledgments to be generated instead. Note that the support for 999 Implementation Acknowledgments does not include CTX segment generation.

reportSegmentErrors="true"

Report segment error details to sender in 997/999 flag. If true, the details of any segment errors are included in a generated 997/999. If false, the details are not included.

includeFASchema="true"

Expect 997 or 999 Functional Acknowledgments and include 997/999 schema. By default, the schema for 997/999 acknowledgment transaction sets is automatically included in the set of schemas used by the X12 EDI Module. If false, you need to directly specify the 997 and/or 999 schema if you want these to be processed as input. The schemas used for generating 997 or 999 Functional Acknowledgments are hard coded and cannot be modified.

Writer parameters control the writer operation (all are optional, with default values as shown):

XML Value Visual Studio Option

dataSeparator="*"

Data element separator character. The configured value is used by default for all output messages, but can be overridden at the message level.

componentSeparator=">"

Component separator character. The configured value is used by default for all output messages, but can be overridden at the message level.

repetitionSeparator="U"

Repetition separator character. The configured value is used by default for all output messages, but can be overridden at the message level. The value U means repetitions are not used.

segmentTerminator="~"

Segment terminator character. The configured value is used by default for all output messages, but can be overridden at the message level.

lineEnding="NONE"/"LF"/"CRLF"/"CR"

Line ending to add between segments, which defaults to NONE. This allows you to add line endings between segments to improve the readability of the output message text.

sendUniqueGroupNumbers="false"

Send unique Group Control Numbers. By default, functional group control numbers are assigned sequentially within each interchange and are reused in different interchanges. If true, this instead assigns unique group numbers across all interchanges sent to the same partner and application (as determined by the interchange sender and receiver identification, combined with the functional group sender and receiver application codes).

sendUniqueTransactionNumbers="false"

Send unique Transaction Set Control Numbers. By default, transaction set control numbers are assigned sequentially within each functional group and are reused in different groups. If true, this instead assigns unique transaction set numbers across all interchanges sent to the same partner and application (as determined by the interchange sender and receiver identification, combined with the functional group sender and receiver application codes).

implementationConventionReference=""

Implementation convention reference for transactions (ST segment). If this value is set, it is used as the ST Implementation Convention Reference unless overridden in the message parameters.

initialInterchangeNumber="1"

The initial Interchange Control Number used for outgoing messages.

initialGroupNumber="1"

The initial Group Control Number used for outgoing messages.

initialSetNumber="1"

The initial Transaction Set Control Number used for outgoing messages.

ackRequested="false"

Request acknowledgments for sent transactions flag. If true, 997/999 acknowledgments are requested for all sent transactions.

defaultUsageIndicator="P"

Default ISA15 interchange usage indicator ("I" for Information, "P" for Production Data, "T" for Test Data).

To Set Your Schema Locations

You can configure schema locations in the Anypoint Studio XML view.

In Anypoint Studio, switch to the XML view by clicking Configuration XML and modify your X12 EDI configuration to include a list of all the schemas you wish to include by adding an <http://edischema[edi:schema]> element for each document type:


         
      
1
2
3
4
5
<x12-edi:config name="X12_EDI__Configuration" identKeys="true" doc:name="X12 EDI: Configuration">
  <x12-edi:schemas>
    <x12:schema value="/x12/005010/850.esl"/>
  </x12-edi:schemas>
</x12-edi:config>

After you create a global element for your X12 EDI, configure any schemas and operations.

About the X12 Message Structure

The connector enables reading or writing of X12 documents into or from the canonical EDI message structure. This structure is represented as a hierarchy of Java Maps and Lists, which can be manipulated using DataWeave or code. Each transaction has its own structure, as defined in the schemas, as outlined above.

The message itself contains the following keys (some of which only apply to either the read operation or the write operation, as indicated):

Key name Description

Delimiters (optional)

The delimiters used for the message (set based on the last interchange processed by a read operation). If set for a write operation this overrides the values in the module configuration. The characters in the string are interpreted based on position, in the following order: (data separator), (sub-element separator), (repetition separator, or 'U' if none), (segment terminator).

Errors (read only)

A list of errors that are associated with the input as a whole, or with interchanges with no valid transaction sets. See the X12Error structure description in the To Read and Validate X12 EDI Messages section below.

FunctionalAcksGenerated (read only)

A list of 997 or 999 acknowledgments (as configured) that were generated by the module during the read operation. To send an acknowledgment, see the Sending Acknowledgments section below.

Group (write only)

Map of GS group header segment values used as defaults when writing groups.

Interchange (write only)

Map of ISA interchange header segment values used as defaults when writing interchanges.

InterchangeAcksGenerated (read only)

A list of TA1 acknowledgments that were generated by the module during the read operation.

InterchangeAcksReceived (read only)

A list of TA1 acknowledgments that were received by the module during the read operation.

InterchangeAcksToSend (write only)

A list of TA1 acknowledgments that are to be sent by the module during the write operation.

Transactions

A hierarchy of the transaction sets which were read by the module during a read operation, or which are to be sent by the module during a write operation. The value of this top-level key is a map with standard versions as keys, in the form "v005010" (for instance). For example, if you are using version 005010 850 and 855 transaction sets, the Transactions would contain a map with one key, "v005010". The value of this key would be another map, this one with two keys, "850" and "855". Each of these would contain a list of individual 850 and 855 transaction sets that you could then process. If you’re using 997 functional acknowledgments "997" is the key for a list of 997 transaction sets.

Individual transaction sets have their own maps, with the following keys:

Key Description

Detail

Map of segments or loops from the detail section of the transaction set. Values are maps for segments or loops which occur at most once, lists of maps for values which may be repeated.

Errors (read only)

A list of errors which are associated with the transaction set. (See the X12Error class description in the Reading and Validating EDI Messages section below.)

Group

Map of GS group header segment values. When reading a message, this map is the actual data from the enclosing group (a single map linked from all transaction sets in the group). When writing a message, these values are used for creating the enclosing group. Values not populated in this map default to the values from the Group map at the message level.

Heading

Map of segments or loops from the heading section of the transaction set. Values are maps for segments or loops which occur at most once, lists of maps for values which may be repeated.

Id

Transaction ID, which must match the key of the containing transaction list.

Interchange

Map of ISA interchange header segment values. When reading a message, this map is the actual data from the enclosing interchange (a single map linked from all transaction sets in the interchange). When writing a message, these values are used for creating the enclosing interchange (gathering transactions with the same interchange values into a single interchange, regardless of whether the actual maps are the same or not). Values not populated in this map default to the values from the Interchange map at the message level.

Name

Transaction set name.

SetHeader

Map of ST transaction set header segment values. This gives the actual header data for a read operation, and allows you to provide overrides for configuration settings for a write operation.

Summary

Map of segments or loops from the summary section of the transaction set. Values are maps for segments or loops which occur at most once, lists of maps for values which may be repeated.

Generated 997/999 functional acknowledgment transactions differ from received messages in their handling of interchange information:

Key name Description

Interchange

Map of ISA interchange header segment values. For functional acknowledgments generated by receive processing, this map is a copy of the data for the containing interchange with sender and receiver identification components (ISA05/ISA06 and ISA07/ISA08) interchanged. When writing a message, these values are used for creating the enclosing interchange (gathering transactions with the same interchange values into a single interchange, regardless of whether the actual maps are the same or not). Values not populated in this map default to the values from the Interchange map at the message level.

TA1 interchange acknowledgments are in the form of maps representing the TA1 segment data and linked to data on the corresponding interchange:

Key name Description

Interchange

Map of ISA interchange header segment values. For TA1 acknowledgments generated by receive processing, this map is a copy of the data for the interchange matching the TA1 with sender and receiver identification components (ISA05/ISA06 and ISA07/ISA08) interchanged. When writing a message, these values are used for creating the enclosing interchange (gathering transactions with the same interchange values into a single interchange, regardless of whether the actual maps are the same or not). Values not populated in this map default to the values from the Interchange map at the message level.

About Time Fields

All X12 Time fields are represented as Integer values for the number of milliseconds. For example, if a message has the value 024020, its DataWeave mapping appears as 9620000 milliseconds.

The value 024020 is in the format "HHMMSS", so if we convert it to milliseconds, use this formula:

(02*3600000) + (40*60000) + (20*1000) = 9620000

To Read and Validate X12 EDI Messages

  1. To read an X12 message, search the palette for X12 EDI and drag the X12 Read operation into a flow.

  2. Go to the properties view, select the connector configuration you created above and select the Read operation. This operation reads any byte stream into the structure described by your X12 schemas.

The X12 module validates the message when it reads it in. Message validation includes checking the syntax and content of envelope segments ISA, GS, GE, and IEA as well as the actual transaction sets in the message. Normally errors are both logged and accumulated and reported in either TA1 technical acknowledgment segments or 997 acknowledgment transaction sets, and all accepted transaction sets (whether error free or with non-fatal errors) are passed on for processing as part of the output message Map. Errors in reading the input data results in exceptions being thrown.

Error data entered in the receive data map uses the X12Error class, a read-only JavaBean with the following properties:

Property Description

segment

The zero-based index within the input of the segment causing the error.

segTag

The tag for the segment causing the error.

fatal

Flag for a fatal error, meaning the associated transaction set, group, or interchange was rejected as a result of the error.

errorType

Enumeration for the different types of errors defined by the X12 standards: INTERCHANGE_NOTE, GROUP_SYNTAX, TRANSACTION_SYNTAX, SEGMENT_SYNTAX, or ELEMENT_SYNTAX.

errorCode

Error code, as defined by the X12 standard for the indicated type of error.

errorText

Text description of the error.

errorLevel

Enumeration for the different levels of errors: ROOT_LEVEL, INTERCHANGE_LEVEL, GROUP_LEVEL, or TRANSACTION_LEVEL.

interchangeId

Interchange identifier, if errorLevel INTERCHANGE_LEVEL or above.

groupId

Group identifier, if errorLevel GROUP_LEVEL or TRANSACTION_LEVEL.

transactionId

Interchange identifier, if errorLevel TRANSACTION_LEVEL.

Error data is returned by the read operation as optional lists with the "Errors" key at every level of the data structure. At the transaction set level, this list contains non-fatal errors encountered during the parsing of that transaction set. At the interchange level, this list contains errors (both fatal and non-fatal) for transaction sets with fatal errors. At the root level of the read, this list contains both interchange errors and every other error reported at any nested level.

To Write X12 EDI Messages

To write an outgoing message, search the palette for X12 EDI and drag the X12 Write operation into a flow. Construct an outgoing X12 EDI message according to the structure as defined above for input to the write operation. If no errors are found in the write operation the normal flow continues. Otherwise, an exception is thrown which includes an array of X12Error instances, the same as returned by the Read operation (documented above).

To Send Functional Acknowledgments

Sending generated functional acknowledgments (997 or 999 transaction sets) is the same as writing any other EDI message, except you set the transactions to the acknowledgments that were generated during the read operation.

For example:

Ack Flow Diagram


         
      
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<x12-edi:read config-ref="X12_EDI__Configuration" doc:name="Read EDI Doc"/>
  ...
<dw:transform-message doc:name="Create Outgoing Acks Message">
    <dw:set-payload><![CDATA[%dw 1.0
%output application/java
---
{
        TransactionSets: {
                v005010: {
                        '997' : payload.FunctionalAcksGenerated
                }
        }
}]]></dw:set-payload>
</dw:transform-message>
<x12-edi:write config-ref="X12_EDI__Configuration" doc:name="Send Acks"/>

The generated functional acknowledgments have interchange data set up for sending back to the sender of the original message, so you don’t need to change anything in the transactions to do the send.

If you use 999 acknowledgments, add any required CTX segments yourself to the basic structure generated by the X12 Module. The X12 connector does not track implementation convention changes to the base transaction set structure.

Sending Interchange Acknowledgments

To send interchange acknowledgments (TA1 segments), set the value of the InterchangeAcksToSend key in the message map to the list of TA1 segment maps to be sent. The generated TA1 segments have interchange data set up for sending back to the sender of the original message, so you don’t need to change anything in the segment data to do the send.