Parse and Transform an Inbound EDI Message

You can parse and transform an EDI message to match the XML format that a backend application can understand. The previous sections in this chapter described how to create a basic inbound integration using the EDI translate action. This section describes how to modify that integration to include a transformation step.

The previous integration returned the EDI-XML content directly in the REST Adapter response. This use case changes the REST Adapter response schema to return a FusionPurchaseOrder, a mock backend application schema for a purchase order. Because there is no real backend application to contact, the XML message is returned to the caller. To make this integration more useful, you can modify it further to add an adapter invoke connection that sends the transformed message to a backend application. Once you do that, you have an end-to-end purchase order flow.

Error handling is also introduced in the integration. When an EDI translation fails, an error is returned instead of transforming it to a backend message.

This use case is described in high-level steps below. It handles an input containing a single EDI document. To handle an EDI batch file, see Process an Inbound EDI Batch File Using the Stage File Action.



Perform the following changes to the integration created earlier in this chapter:

  1. Change the response schema in the Receive-EDI REST Adapter trigger connection.
    1. Edit the Receive-EDI REST Adapter trigger connection created in Configure the REST Adapter Trigger Connection.
    2. Go to the Response tab.
    3. Select XML Schema as the response payload format and XML as the media type.
    4. For the Schema Location, upload an .xsd file with the following content:
      <?xml version="1.0" encoding="UTF-8"?>
      <schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.example.org/PurchaseOrder" xmlns:tns="http://www.example.org/PurchaseOrder" elementFormDefault="qualified">
          <element name="FusionPurchaseOrder"
              type="tns:FusionPurchaseOrderType">
          </element>    
          <complexType name="FusionPurchaseOrderType">
              <sequence>
                  <element name="SenderId" type="string"></element>
                  <element name="orderNumber" type="string"></element>
                  <element name="orderDate" type="dateTime"></element>
                  <element name="quoteID" type="string"></element>
                  <element name="totalAmount" type="float"></element>
                  <element name="currencyCode" type="string"></element>
                  <element name="currencyConversionRate" type="float"></element>
                  <element name="lineItems" type="tns:OrderLineItem" maxOccurs="unbounded" minOccurs="1"></element>
                  <element name="billingAddress" type="tns:Address"></element>
                  <element name="shippingAddress" type="tns:Address"></element>
                  <element name="contact" type="tns:Contact"></element>
              </sequence>
          </complexType>
          <complexType name="OrderLineItem">
              <sequence>
                  <element name="SKU" type="string"></element>
                  <element name="Quantity" type="float"></element>
                  <element name="unitOfMeasure" type="string"></element>
                  <element name="comments" type="string"></element>
                  <element name="price" type="float"></element>
                  <element name="amount" type="float"></element>
              </sequence>
          </complexType>
          <complexType name="Address">
              <sequence>
                  <element name="Name" type="string"></element>
                  <element name="AddressLine1" type="string"></element>
                  <element name="AddressLine2" type="string"></element>
                  <element name="AddressLine3" type="string"></element>
                  <element name="City" type="string"></element>
                  <element name="State" type="string"></element>
                  <element name="Country" type="string"></element>
                  <element name="ZipCode" type="string"></element>
              </sequence>
          </complexType>
          <complexType name="Contact">
              <sequence>
                  <element name="name" type="string"></element>
                  <element name="phone" type="string"></element>
                  <element name="email" type="string"></element>
              </sequence>
          </complexType>
      </schema>
  2. Add a switch action after the EDI-Translate REST Adapter.
    1. For the If branch, enter the following expression:
      $EDI-Translate/nssrcmpr:executeResponse/nsmpr6:TranslateOutput/nsmpr6:translation-status = "Success" or $EDI-Translate/nssrcmpr:executeResponse/nsmpr6:TranslateOutput/nsmpr6:translation-status = "Warning"

      Note:

      Your namespace prefix may include different values than nssrcmpr and nsmpr6.

      This expression indicates that if TranslateOutput > translation-status has a value of Success or Warning, then take this route. This is referred to as the success route.

    2. Call the Otherwise branch the error route for error handling.
  3. In the error route, add a fault return action.
    This creates a map before the fault return action.
    1. In the map, connect the useful error information inside TranslateOutput > validation-errors to the fault error details. See EDI Translate Input and Output Schemas Explained for a description of elements inside TranslateOutput.

      The error route does not transform the message (or prepare it for delivery to a backend application). Instead, it returns a 5xx error.

  4. In the success route, add a message transformation step.
    Message transformation is done using a map action.
    1. Add a map and a return action to this route.

      The map has fairly complex mappings from the EDI-XML purchase order to the FusionPurchaseOrder. Performing this mapping requires some expertise on the target application schema and EDI X12 schema.



      Elements are mapped from the X12 BEG and REF segments, purchase order line items from the PO1 loop, and the purchase order summary from CTT and AMT segments near the end.

      Not all elements from the EDI-XML schema are mapped because the FusionPurchaseOrder schema is smaller and comparatively much simpler than the rich structure defined in the EDI X12 schema. The map transforms the EDI-XML message to a FusionPurchaseOrder message that is ready to be consumed directly by a backend application.

  5. Activate the integration and use any REST client such as postman to send the following EDI X12 850 purchase order:
    ISA|00|          |00|          |01|111111T        |01|22222          |190312|0845|U|00401|000001894|0|T|~
    GS|PO|0124578|ACME|20190312|084515|0123456|X|004010
    ST|850|1234
    BEG|00|NE|PO-4503000||20190312|QO-1032
    CUR|2L|USD|1.0000
    REF|IT|999|Global Chips
    REF|WO|P8923.5
    REF|KY||Standard Terms and conditions will apply
    PER|BD|JAMES SMITH|TE|1112223333|EM|jamess@globalchips.com
    FOB|PC|OR|ORIGIN FREIGHT COLLECT|02|FOB
    ITD||3|||||10|||||P03R
    DTM|002|20190329
    TD5|B||05||Ground
    N1|BT|Global Chips
    N2|ACCOUNTS PAYABLE
    N3|P.O. BOX 1111
    N4|NEW YORK|NY|10001|US
    PO1|00001|1|EA|74.99|PE|BP|5566|VN|AB-1264
    PID|F||||AB-1264 BRACKET ASSY WITH SPRING
    PO1|00002|1|EA|25.00|PE|BP|7264|VN|DE-1834
    PID|F||||DE-1834 GEAR BOX PACKAGE
    CTT|2|2
    AMT|TT|99.99
    SE|22|1234
    GE|1|0123456
    IEA|1|000001894

    You receive a response with the following XML message:

    <tns:FusionPurchaseOrder xmlns:tns="http://www.example.org/PurchaseOrder">
        <tns:SenderId>111111T</tns:SenderId>
        <tns:orderNumber>PO-4503000</tns:orderNumber>
        <tns:orderDate>20190312</tns:orderDate>
        <tns:quoteID>QO-1032</tns:quoteID>
        <tns:totalAmount>99.99</tns:totalAmount>
        <tns:currencyCode>USD</tns:currencyCode>
        <tns:currencyConversionRate>1.0000</tns:currencyConversionRate>
        <tns:lineItems>
            <tns:SKU>AB-1264</tns:SKU>
            <tns:Quantity>1</tns:Quantity>
            <tns:unitOfMeasure>EA</tns:unitOfMeasure>
            <tns:comments>AB-1264 BRACKET ASSY WITH SPRING</tns:comments>
            <tns:price>74.99</tns:price>
        </tns:lineItems>
        <tns:lineItems>
            <tns:SKU>DE-1834</tns:SKU>
            <tns:Quantity>1</tns:Quantity>
            <tns:unitOfMeasure>EA</tns:unitOfMeasure>
            <tns:comments>DE-1834 GEAR BOX PACKAGE</tns:comments>
            <tns:price>25.00</tns:price>
        </tns:lineItems>
        <tns:billingAddress>
            <tns:Name>Global Chips</tns:Name>
            <tns:AddressLine1>ACCOUNTS PAYABLE</tns:AddressLine1>
            <tns:AddressLine2>P.O. BOX 1111</tns:AddressLine2>
            <tns:AddressLine3/>
            <tns:City>NEW YORK</tns:City>
            <tns:State>NY</tns:State>
            <tns:Country>US</tns:Country>
            <tns:ZipCode>10001</tns:ZipCode>
        </tns:billingAddress>
        <tns:contact>
            <tns:name>JAMES SMITH</tns:name>
            <tns:phone>1112223333</tns:phone>
        </tns:contact>
    </tns:FusionPurchaseOrder>
  6. To test a negative case, modify line 1 and replace ISA with any other characters, and submit. This causes the integration to take the error route. An HTTP Error 500 is returned with an error message, including this inner error:
    B2B-01858: Not an EDI X12 native document since the first 3 characters are not 'ISA' (found: 'SDS')
In conclusion, you can use Oracle Integration to accept an inbound EDI message, parse it, check for syntax errors in the EDI, transform it, and send it to a backend application.