Generate Outbound EDI From An Application Message

You can use Oracle Integration to create an EDI X12 document from a backend application XML message using the EDI translate action. The EDI X12 document is then sent to a trading partner.

The following topics are described:

  • Transform a backend application XML message using the map action into an edi-xml-document that becomes an input to the EDI translate action in the outbound direction.
  • Specify delimiters of your choice to be used in the EDI.
  • Using a lookup, specify EDI identifiers to be used in the EDI.
  • Using the EDI translate action for outbound direction, convert the edi-xml-document into an EDI X12 document, and send it to your trading partner.
  • If the trading partner sends back an EDI X12 997 (Functional Acknowledgment) document, use a separate integration to receive the 997 Ack message and interpret what it says.

Note:

In this use case, the backend application message is received as XML over REST. However Oracle Integration also supports JSON over REST. Alternatively you can use any other adapter, such as the Oracle ERP Cloud Adapter, to receive the message. This use case also provides only general guidelines such as usage of a lookup. You can also use alternate methods (such as retrieving the values by querying a database). Use any available action and adapter available in Oracle Integration to satisfy your use case.

Prerequisites

  1. Navigate to Designer > Lookups, and create a new lookup with the name Trading-Partners-Lookup as follows:

  2. Add entries corresponding to the trading partners to which to send outbound EDI documents.
  3. Add the following columns:
    • Trading-Partner-Id
    • EDI_Interchange_Identifier
    • EDI_Group_Identifier
    • EDI_Interchange_Id_Qualifier
    This lookup is used in the integration to fetch the EDI identifiers corresponding to a given trading partner.
  4. Add an entry for the host company, so your company's EDI identifiers are also entered.

General Guidelines to Build an Integration for Outbound EDI Processing

  1. Receive the backend application XML message using a REST Adapter trigger connection.
    One of the elements in the input XML must specify a trading partner that is the recipient of the outbound EDI. For example, the input XML has:
    <tradingPartnerId>Micro Parts</tradingPartnerId>

    In this case, the recipient trading partner is Micro Parts, which must have a matching entry in the lookup you created. The lookup allows the integration to retrieve EDI identifiers for Micro Parts dynamically.

  2. Add the EDI translate action next and configure it for the outbound direction.
  3. Select EDI X12 as the Document Standard, 4010 as the Document Version, and 850 (Purchase Order) as the Document Type.
  4. Configure the map action that occurs between the REST Adapter trigger connection and the EDI translate action to transform the backend application XML message to the edi-xml-document.

    Reference the lookup in the map expression to retrieve the EDI identifiers. This is explained later in this section.

  5. Check if the EDI translate completed successfully by verifying that translation-status is either a Success or Warning.

    If successful, use an adapter invoke connection to send the EDI document to the trading partner. For example, use an FTP Adapter invoke connection to deliver the EDI document to an external B2B Value Added Network (VAN) provider to forward to a trading partner in a final push.

  6. Create a separate integration using the inbound EDI pattern described in Process An Inbound EDI Batch File Using Stage File and Send a 997 Acknowledgment to receive the EDI X12 997 (Functional Acknowledgment) document type. This is explained in more detail later in this section.

Specifying EDI Delimiters of Your Choice

The EDI translate action enables you to specify EDI delimiters of your choice by assigning them to XML attributes inside the edi-xml-document > headers > interchange-ctrl element. If you don't set a value, a default value is used.

Assign a single ASCII character to any of the attributes. To specify special characters, nonprintable characters, or Unicode characters, see section Elements in TranslateInput for the supported values.

The following attributes represent each delimiter:

EDI X12 Delimiter XML Attribute Where to Set a Value Default Value
Element delimiter edi-xml-document > headers > interchange-ctrl > attribute 'element-separator' *
Segment terminator edi-xml-document > headers > interchange-ctrl > attribute 'segment-terminator' ~
Composite element delimiter edi-xml-document > headers > interchange-ctrl > attribute 'subelement-separator' :

Repetition separator

(only used in X12 4020 and newer versions)

edi-xml-document > headers > interchange-ctrl > attribute 'repetition-separator' N/A

Note:

Ensure that data values do not contain any of the delimiter characters. Specify delimiters that do not occur in the data. Otherwise, the generated EDI cannot be parsed correctly. Each delimiter must also use a distinct character. Using the same character for any two delimiters generates an invalid EDI message.

Inserting EDI Identifiers in the Interchange and Group Headers

Outbound EDI X12 mandates the interchange and group envelope header segments (the ISA and GS segments) to specify EDI identifiers. These are mandatory elements that are not assigned default values. You must specify values for the six header fields described below, at a minimum. The remaining header fields are assigned default values.

The lookup created earlier is used to populate these values:
EDI X12 Header Field Guidelines for Mapping Based on the Trading-Partner-Lookup Target Element
ISA05: Interchange Sender ID Qualifier

This is a two-character value that must use a code from an X12 code list for this element.

The expected value is the interchange ID qualifier of the sending party, which is your company (that is, the host company). From the lookup, fetch the EDI_Interchange_Id_Qualifier for the Host Company entry and assign that as the value.

A sample mapping expression is:



dvm:lookupValue ("tenant/resources/dvms/Trading-Partners-Lookup", "Trading-Partner-Id", "Host Company", "EDI_Interchange_Id_Qualifier", "Trading-Partners-Lookup error" )
edi-xml-document headers > interchange-ctrl > attribute 'sender-id-qualifier'
ISA06: Interchange Sender ID

The value is a maximum of 15 characters.

The expected value is the interchange ID of the sending party, which is your company (that is, host company). From the lookup, fetch the EDI_Interchange_Identifier for the entry Host Company and assign that as the value. For example, the mapping expression is:
dvm:lookupValue ("tenant/resources/dvms/Trading-Partners-Lookup", "Trading-Partner-Id", "Host Company", "EDI_Interchange_Identifier", "Trading-Partners-Lookup error" )
edi-xml-document > headers > interchange-ctrl > attribute 'sender-id'
ISA07: Interchange Receiver ID Qualifier

This is a two-character value and must use a code from an X12 code list for this element.

The expected value is the interchange ID qualifier of the receiving party, which is your remote trading partner. From the lookup, fetch the EDI_Interchange_Id_Qualifier for the entry specified by the input tradingPartnerId element, and assign that as the value. For example, the mapping expression is:
dvm:lookupValue ("tenant/resources/dvms/Trading-Partners-Lookup","Trading-Partner-Id", /nssrcmpr:execute/tns:AcmePurchaseOrder/tns:tradingPartnerId, "EDI_Interchange_Id_Qualifier", "Trading-Partners-Lookup error" ) 
edi-xml-document > headers > interchange-ctrl > attribute 'receiver-id-qualifier'
ISA08: Interchange Receiver ID

The value is a maximum of 15 characters.

The expected value is the interchange ID of the receiving party, which is your remote trading partner. From the lookup, fetch the EDI_Interchange_Identifier for the entry specified by the input tradingPartnerId element, and assign that as the value. For example, the mapping expression is:
dvm:lookupValue ("tenant/resources/dvms/Trading-Partners-Lookup", "Trading-Partner-Id",/nssrcmpr:execute/tns:AcmePurchaseOrder/tns:tradingPartnerId,"EDI_Interchange_Identifier", "Trading-Partners-Lookup error" )
edi-xml-document > headers > interchange-ctrl > attribute 'receiver-id'
GS02: Application Sender's Code

The value is between 2 and 15 characters.

The expected value is the application sender's code of the sending party, which is your company (that is, host company). From the lookup, fetch the EDI_Group_Identifier for the entry Host Company, and assign that as the value. For example, the mapping expression is:

dvm:lookupValue ("tenant/resources/dvms/Trading-Partners-Lookup","Trading-Partner-Id", "Host Company", "EDI_Group_Identifier", "Trading-Partners-Lookup error" )
edi-xml-document > headers > group > app-senders-code
GS03: Application Receiver's Code

The value is between 2 and 15 characters.

The expected value is the application receiver's code of the receiving party, which is your remote trading partner. From the lookup, fetch the EDI_Group_Identifier for the entry specified by the input tradingPartnerId element, and assign that as the value. For example, the mapping expression is:

dvm:lookupValue ("tenant/resources/dvms/Trading-Partners-Lookup", "Trading-Partner-Id", /nssrcmpr:execute/tns:AcmePurchaseOrder/tns:tradingPartnerId, "EDI_Group_Identifier", "Trading-Partners-Lookup error" )
edi-xml-document > headers > group > app-receivers-code

EDI Control Numbers Are Generated Automatically

An outbound EDI X12 document also mandates three control numbers, and the EDI translate action generates those automatically with unique incremented values.
  • Interchange control number, populated in the ISA13 element and IEA02 element.
  • Group control number, populated in the GS06 element and GE02 element.
  • Transaction set control number, populated in the ST02 element and SE02 element.

Similarly, the Date and Time fields in the Interchange and Group headers are also automatically generated based on the current timestamp. Other remaining fields are assigned default values, including those in the edi-xml-document > trailers element.

You can override any of the default values by assigning them with your values explicitly to the interchange-ctrl and group attributes.

Checking For Translation Errors

You must check for validation errors that may be reported during EDI generation. Validation errors mean that the generated EDI is syntactically invalid and is likely rejected by your trading partner. You must resolve the errors by correcting the mappings or the input data.

Check for validation errors using a switch action and the success condition as TranslateOutput > translation-status = "Success" or TranslateOutput > translation-status = "Warning". Otherwise, if TranslateOutput > translation-status is 'Error', it indicates there are critical validation errors.

Output EDI Payload

If EDI translation completes successfully (with no errors or only warnings), the TranslateOutput > edi-payload element is populated with the generated EDI. This value is Base64-encoded and you must apply a decode64 function or variant to get the actual EDI document at the point of delivery to a trading partner (for example, while writing it to file to be sent through an FTP Adapter invoke connection).

Receiving Inbound EDI X12 997 Functional Acknowledgments

When the remote trading partner receives your EDI document, an EDI X12 997 document is processed and sent back as an interim acknowledgment. An 997 Ack message reports a status, such as accepted or rejected, indicating whether your trading partner parsed the original EDI document you sent. When you receive a 997 Ack message, it is important to inspect it to determine the outcome reported by your trading partner. If rejected, you can take corrective actions.

General Guidelines to Build an Integration to Receive an 997 Ack

You must build a separate integration using the inbound EDI pattern described in Parse and Transform an EDI Message.

  1. In the EDI translate action, select the 997 (Functional Acknowledgment) document type.
  2. Remove the transformation step, as this integration does not need to produce a backend application message. Backend systems typically do not need or support the B2B layer acknowledgments.
  3. Add a check for the functional acknowledgment status field located at, TranslateOutput > edi-xml-document > func-ack-report (same as Functional acknowledgment report) > func-ack-status.
    Description of edi_map.png follows
    Description of the illustration edi_map.png

    This element has a value of Success, Warning, or Error to represent the acceptance status reported by your trading partner. In case of an error, the func-ack-details field is populated with plain text describing the interpretation of what the 997 Ack message says.

    See the description for each of the child elements under func-ack-report (same as Functional acknowledgment report) in the chapter EDI Translate Input and Output Schemas Explained.

    Note:

    The EDI translate action never generates another 997 Ack message when it parses an inbound 997 Ack document. The EDI X12 standard defines the behavior that there is no Ack for an Ack message. Otherwise, it implies a procedural infinite loop.