Process an Inbound EDI Batch File Using the Stage File Action

Learn how to create a B2B flow, using the stage file and B2B actions, to process an inbound EDI batch file and send a functional acknowledgment for the file back to the sender.

Topics:

• Prerequisites to Set Up the Integration

• Build an Integration to Process the EDI Batch File

• Configure a Stage File Action to Debatch the EDI File

• Process an EDI Batch File with Heterogeneous Documents

• Send an EDI X12 997 Functional Acknowledgment

Prerequisites to Set Up the Integration

Review the prerequisites to set up a B2B flow in Oracle Integration to handle an inbound EDI batch file.

Before you begin configuring this example flow, you must:

• Have an external SFTP server to host the inbound EDI documents and the outbound functional acknowledgment (997) documents. Create an FTP connection to connect to the SFTP server. See Create an FTP Adapter Connection.
• Be familiar with creating, configuring, and activating integration flows in Oracle Integration. For a step-by-step guide to set up a basic B2B flow, see Create a Simple Integration Using B2B for Oracle Integration.
• Be familiar with the FTP invoke operation and the general usage pattern of the stage file action in integrations. See Process Files in Scheduled Integrations with a Stage File Action.

Note:

This example use case provides only a general guideline to implement the EDI batch file processing. If you do not have an external SFTP server, you can use any other adapter in place of the FTP Adapter to fetch the EDI file, and use any actions or constructs to build an integration to suit your use case. For instance, you can use the streamReference input available in the REST Adapter trigger connection of the Parse and Transform an Inbound EDI Message example as the input file. Subsequently, you can apply the stage file action and other processing steps on that file.

Build an Integration to Process the EDI Batch File

Follow the general guidelines provided here to build the example integration flow.

1. Download the incoming EDI batch file to Oracle Integration.

   You can use an FTP Adapter invoke connection to download a single file. Use the two FTP Adapter invoke connection patterns if you want to process multiple files from a directory on a remote SFTP server, where one FTP Adapter invoke connection retrieves a list of files, and another downloads the files.

2. Use a stage file action to debatch EDI documents from the downloaded batch file. See Configure a Stage File Action to Debatch the EDI File.

   Let's assume you have received a batch of fifty EDI purchase orders in a single file. The stage file action splits the file into fifty individual EDI purchase orders and offers them as repeating elements.

3. Using a for-each action, iterate over the repeating elements to handle one EDI document at a time.
4. Use the B2B action and parse one EDI document at a time.

   As the for-each action iterates over each individual EDI document, the B2B action keeps track that the original batch contains fifty EDI purchase orders, and finally performs some additional processing for the last document in the batch.

5. After the entire batch is parsed, send the functional acknowledgment document back to the original sender. See Send an EDI X12 997 Functional Acknowledgment.

   The B2B action generates an EDI X12 997 (Functional Acknowledgment) for the last EDI document it handles from a batch. In this example of fifty documents, the B2B action processes the first forty-nine EDI purchase orders routinely but includes an EDI X12 997 (Functional Acknowledgment) document to the fiftieth EDI purchase order. This acknowledgment document contains the status information for the entire batch of fifty documents, and according to the EDI X12 standard, you should transmit this document back to the originating trading partner after the entire batch has been parsed. If the B2B action has generated the 997 document, write it to a separate file and transmit the file to the trading partner using the FTP Adapter invoke connection and write file operations.

6. Check if the B2B action completed successfully.

   You can do this by verifying if translation-status is either a Success or Warning. If the status is either of the two, use a map action to transform the EDI-XML into a backend application message. Finally, use an invoke connection from a suitable adapter and send the message to the backend application.

7. After a file is processed, rename it with the .processed file extension to ensure that the same file is not picked for processing again in a future execution.

Configure a Stage File Action to Debatch the EDI File

Here's a list of key tasks you need to perform to configure the stage file action in your integration.

1. While configuring the stage file archive, select Read File in Segments in the Choose Stage File Operation field, which is present on the configuration wizard's Configure Operation page.
2. On the Schema Options page, specify the structure of the file contents as EDI document as shown in the following image. Specifying this option results in debatching of the EDI batch file into individual documents.

   
   Description of the illustration stagefile-config.png

3. The stage file action configured for EDI documents generates the following output structure:
   
   
   Description of the illustration edi_stage_file.png
   
   

   From the input batch of EDI documents, a repeating element EDI-Document-Instance is generated for each EDI document debatched. For example, if the input is a batch of fifty, there are fifty EDI-Document-Instance elements. If the input has one single EDI document, then only one EDI-Document-Instance element is generated.

   Note:

   In your integration, use a for-each action to iterate over the repeating element EDI-Document-Instance.
4. Configure the Map to EDI-Translate action.
   This action is the map that transfers data from the stage file action to the EDI-Translate action. The data includes the edi-payload as well as other elements required to track the state of an EDI batch; therefore, you must map the following elements:

   • edi-payload
   • tracking-info
   • edi-encoding
   • routing-info (map each child element from source to target)
   • validation-errors to passthrough-errors (map each child element from source to target)
   • (Optional) input-source-context from the target. See B2B Action Input and Output Schema Reference.

   
   Description of the illustration stagefile-map.png

   Note:

   If your input file has a single EDI document (not a batch), the stage file action simply generates a single EDI-Document-Instance in the repeating element structure. In such a case, the for-each action iterates only once. An integration designed to handle an EDI batch, therefore, also works for single EDI document files. It is a special case that has a batch of one.

Error Handling

For each EDI-Document-Instance, the element validation-errors is populated with any errors detected during debatching. There are two important error categories:

• EDI-Document-Instance > validation-errors > error > category = "FATAL"

  This error category indicates that a critical error was found in the input EDI, causing the entire EDI file to be rejected (assuming the input file contained one X12 interchange). does not generate an X12 TA1 document to automatically report this error to the trading partner. Therefore, you must notify an administrator and work with the sender trading partner to have them correct and resend the file. A message with fatal errors must not be forwarded to a B2B action.

  Example error scenarios: The interchange/group control number is missing or the interchange control numbers in the ISA and IEA segments are not identical.

• EDI-Document-Instance > validation-errors > error > category = "GROUP"

  This error category indicates that an X12 functional group level error, which caused the entire X12 Group to be rejected. For this type of error, simply forward these errors to the next B2B action so that it can generate a proper EDI X12 997 Functional Acknowledgment that indicates the group was rejected. This is done with the map action explained later.

  Example error scenarios: If the group control numbers in the GS and GE segments are not identical.

Note:

The structural errors above are uncommon because the EDI is typically computer-generated. Nevertheless, it is good practice to incorporate error handling in your integration.

The following portion of an integration shows a stage file action named Debatch-EDI-File-Sc, a for-each action, a switch action with a route that checks for the presence of fatal errors, and another route that goes to a B2B action and other related actions:

Description of the illustration edi_error_handle.png

The for-each action For-Each-EDI-Docu uses the iteration variable $EDIRec, in this example.

The integration routes an EDI-Document-Instance with fatal errors and sends it for error handing. When fatal errors are present, the B2B action must not be invoked.

The IF Critical Error route above uses the following logical expression to check for the presence of fatal errors:

count($EDIRec > EDI-Document-Instance > validation-errors > error > category[(text() = "FATAL")]) > 0

Process an EDI Batch File with Heterogeneous Documents

The EDI X12 standard allows a single EDI batch file to contain multiple EDI documents of different types. For instance, a batch file may contain fifty purchase orders and ten invoices, making it a heterogeneous batch.

To handle an EDI batch file containing different document types in your integration:

1. Add a switch action after the for-each action For-Each-EDI-Doc in the flow depicted in Configure a Stage File Action to Debatch the EDI File.
2. In the switch action, add one or more routes based on the value of the $EDIRec > EDI-Document-Instance > routing-info > document-type element or other child elements inside the routing-info element.
3. In each route, add a separate B2B action EDI-Translate, which you then configure to parse a specific document type. Ensure that you correctly route EDI documents to the matching B2B actions. Now, each B2B action parses a different document type, and you can then add error handling, transformations, and other steps to follow the action.

   An example integration showing the routes to handle fatal errors and EDI X12 documents 850, 997, and 810 is shown below. Route 5 handles document types not explicitly routed previously as an error.

   
   
   Description of the illustration edi_complete_int.png
   

The stage file action generates the following elements, as child elements to the routing-info element, that can drive the switch routes in an integration.

Child Element	Description
doc-standard	The EDI standard identified for the document, such as X12.
doc-type	The EDI document type; for example: 850, which represents an EDI X12 purchase order.
doc-version	The EDI version; for example, EDI X12 version 4010.
doc-definition	Not used.
ic-sender-ID-qualifier	The interchange sender ID qualifier that appears in the interchange header (for X12, the value from the ISA05 element of the ISA segment).
ic-sender-ID	The interchange sender ID that appears in the interchange header (for X12, the value from the ISA06 element of the ISA segment).
ic-receiver-ID-qualifier	The interchange receiver ID qualifier that appears in the interchange header (for X12, the value from the ISA07 element of the ISA segment).
ic-receiver-ID	The interchange receiver ID that appears in the interchange header (for X12, the value from the ISA08 element of the ISA segment).
grp-identifier-code	The functional group identifier code that appears in the functional group header (for X12, the value from the GS01 element of the GS segment).
grp-application-sender-code	The functional group application sender's code that appears in the functional group header (for X12, the value from the GS02 element of the GS segment).
grp-application-receiver-code	The functional group application receiver's code that appears in the functional group header (for X12, the value from the GS03 element of the GS segment).

Send an EDI X12 997 Functional Acknowledgment

The B2B action generates an EDI X12 997 (Functional Acknowledgment) for each functional group (GS) in the EDI batch document and handles it from a batch (even if a batch contains only one document).

A batch is defined as one X12 functional group starting with GS and ending with GE segments. A functional group contains one or more EDI documents, each one enveloped between a pair of ST and SE segments. One 997 (Functional Acknowledgment) is generated for one functional group. An X12 interchange is a container for one or more functional groups. The stage file and B2B actions, when used together, understand these envelope structures and generate as many 997 Acks as the number of functional groups that occur inside an X12 interchange.

The following table depicts the output of a B2B action when it parses a batch of fifty EDI purchase orders. Each table row represents an individual EDI document that has been processed.

Note that only a few relevant fields from Elements in TranslateOutput for Inbound EDI are shown as the output here.

EDI Document Number (in a batch of 50)	EDI Translate Output
1	edi-xml-document is populated. functional-ack-present is false. functional-ack is empty.
2	edi-xml-document is populated. functional-ack-present is false. functional-ack is empty. .
...	...
49	edi-xml-document is populated. functional-ack-present is false. functional-ack is empty.
50	edi-xml-document is populated. functional-ack-present is true. functional-ack is populated.

In your integration, check for the functional-ack-present element. When its value is true, write the contents of the functional-ack element to a file (using a decodeBase64ToReference built-in function) and transmit the file to the originating trading partner using another FTP Adapter invoke connection. Note that the functional-ack element is populated as a Base64-encoded string. Therefore, you must apply a decode64 function or a variant of it in the map action to extract the EDI 997 Acknowledgment document.

The acknowledgment part of your integration resembles the following image:

Description of the illustration func-ack.png