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 B2B action. The EDI X12 document is then sent to a trading partner.
This example describes the following aspects:
- Transforming a backend application XML message using the map action into an edi-xml-document that becomes an input to the B2B action in the outbound direction.
- Specifying delimiters of your choice to be used in the EDI.
- Specifying EDI identifiers using a lookup.
- Converting the edi-xml-document into an EDI X12 document and sending it to your trading partner.
- Using a separate integration to receive the EDI X12 997 Ack message and interpreting it.
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
- Navigate to Integrations > Lookups, and create a new lookup with the name
Trading-Partners-Lookupas follows: - Add entries corresponding to the trading partners to which to send outbound EDI documents.
- Add the following columns:
Trading-Partner-IdEDI_Interchange_IdentifierEDI_Group_IdentifierEDI_Interchange_Id_Qualifier
- 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
- 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.
- Add the B2B action next and configure it for the outbound direction.
- Select X12 as the Document Standard, 4010 as the Document Version, and 850 (Purchase Order) as the Document Type.
- Configure the map action that occurs between the REST Adapter trigger connection and the B2B 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.
- Check if the EDI translate completed successfully by verifying that
translation-status is either a
SuccessorWarning.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.
- 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 B2B 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.
| 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: |
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:
|
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:
|
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:
|
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: |
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: |
edi-xml-document > headers > group > app-receivers-code |
EDI Control Numbers Are Generated Automatically
- 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.
- In the B2B action, select the 997 (Functional Acknowledgment) document type.
- 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.
- 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 the illustration edi_map.pngThis 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, B2B Action Input and Output Schema Reference.
Note:
The B2B 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.