Create a Simple Integration Using B2B for Oracle Integration

Using a simple example, let's explore how to use the B2B action in your integration to parse an incoming EDI X12 document.

Topics:

• Create an Integration

• Configure the REST Adapter Trigger Connection

• Configure the B2B Action

• Configure Mapping Actions

• Activate the Integration

• Parse Your First EDI Document

• Test Syntactical Validations

Create an Integration

Let's create a basic, inbound integration flow that receives an EDI document through a REST request, parses and validates the EDI, converts it to XML, and returns the XML in the response.

Note:

This integration flow uses REST for simplicity. You can substitute the REST Adapter trigger connection with any other adapter, such as the FTP Adapter, available in Oracle Integration. Generally, FTP is the transport type used with EDI.

1. In the navigation pane, click Integrations.
2. On the Integrations page, click Create.
3. Select App Driven Orchestration as the style to use. The Create New Integration dialog is displayed.
4. In the What do you want to call your integration? field, enter Inbound EDI via REST, then click Create.

Configure the REST Adapter Trigger Connection

On the integration canvas, click the start node and select Sample REST Endpoint Interface as the trigger connection.

The Configure REST Endpoint wizard opens.

1. On the Basic Info page, enter the following details:
   1. In the What do you want to call your endpoint? field, enter Receive-EDI.
   2. Enter an optional description for the endpoint.
   3. Click Next.
2. On the Resource Configuration page:
   1. Enter /inbound_edi as the endpoint's relative resource URI.
   2. Select POST as the action to perform on the endpoint.
   3. Select to configure both request and response for this endpoint. Click Next.
   
   Description of the illustration rest_trigger_basic.png
3. On the Request page:
   1. Select Binary in the Select the request payload format field.

      Note:

      Most EDI documents contain only textual data, but they may also include line breaks and special characters, which are used as delimiters. A few EDI documents contain raw binary data, such as images, along with text. Therefore, select the request payload format as Binary.
   2. Select Other Media Type as the media type you want the endpoint to receive.
   3. In the Media Type field, enter application/EDI-X12. Click Next.
   
   Description of the illustration rest_trigger_request.png
4. On the Response page:
   1. Select JSON Sample in the Select the response payload format field.
   2. Click the inline link next to enter sample JSON.
   3. In the resulting page, enter the following sample JSON and click OK.

      {
         "translate_result": "xxxx",
         "hasError": false,
         "validationErrors": "xxxx",   "translated_payload":  "xxxx"
      }

   4. Notice that JSON is automatically selected as the response media type.
   
   Description of the illustration rest_trigger_response.png
5. Click Next, and on the Summary page, click Done to complete the REST Adapter configuration.

The integration flow is now represented as follows in the canvas:

Description of the illustration edi_example_rest.png

Configure the B2B Action

Add a B2B action to the flow to translate an EDI document into an Oracle Integration XML message.

1. On the right side of the canvas, click Actions , drag EDI Translate, and drop it after the first Receive-EDI element.
   The Configure B2B Action wizard opens.
2. On the Basic Info page, enter EDI-Translate as the name for the action, and click Next.
3. On the Select Data Formats page, enter the following details:
   1. Leave the Inbound EDI message to Oracle Integration message radio button selected.
   2. Select the document standard as X12.
   3. Select the document version as 4010.
   4. Select the document type as 850 (Purchase Order).
   5. Select the document definition as Standard.
   6. Select the EDI character encoding as UTF8.
   7. Select Yes in the Perform validations on input data? field. Click Next.
4. On the Summary page, click Done to complete the configuration.
   Note that the corresponding mapping element is automatically added to the integration flow:

   
   Description of the illustration edi_example_translate.png

Configure Mapping Actions

Configure data mappings for the EDI-Translate action and Receive-EDI action in order to successfully parse the incoming EDI message and translate it to an XML message.

Configure the Map to EDI-Translate Action

1. Click the Map to EDI-Translate action and select Edit.
2. Map streamReference on the left to edi-payload on the right, within TranslateInput.
3. Click Switch to Developer View in the expression pane that appears at the bottom, and edit the expression for the mapping.

   Prefix the function call encodeReferenceToBase64 to the existing edi-payload expression as follows: oraext:encodeReferenceToBase64 (/nssrcmpr:execute/ns20:streamReference ). Click Save .

   
   Description of the illustration payload_exp.png

   Note:

   Your namespace may be different than ns20.
4. Click Validate and then Close.

Configure the Map to Receive-EDI Action

1. Click the Map to Receive-EDI action and select Edit.
2. Click Developer on the toolbar.
3. Map edi-xml-document (present on the left, under $EDI-Translate > executeResponse > TranslateOutput) to translated_payload, within the response-wrapper on the right.

   Note:

   To achieve this mapping, initially map the @format variable (within edi-xml-document) to translated_payload. In the expression for this mapping, delete /@format and click Toggle on the toolbar. In the Components pane, expand String under Functions. Select the get-content-as-string function and drop it into the expression editor. Copy the existing expression in the editor into the function as follows: oraext:get-content-as-string ($EDI-Translate/nsmpr0:executeResponse/ns20:TranslateOutput/ns20:edi-xml-document ). Click Save .
4. Map translation-status within the same TranslateOutput element to translate_result on the right.
5. Map validation-errors-present to hasError.
6. Map validation-error-report (TranslateOutput > validation-errors) to validationErrors.
7. Click Validate and then Close.

Activate the Integration

Check for errors, save, and activate the integration flow.

1. You'll notice an error notification on the canvas. To resolve it, click Actions Menu in the top-right corner of canvas, and select Tracking.
2. In the resulting dialog, select streamReference on the left and move it to the table on the right.
3. Click Save.
4. Save the integration and click Close.
5. On the Integrations page, click the Activate button against your integration.
6. Click Activate in the Activate Integration dialog.

Parse Your First EDI Document

To execute your sample integration, send a request from a REST client tool, such as Postman.

Create a request definition on the REST client tool as follows:

1. Define the request to send an HTTP POST to the URL:

   http://host:port/ic/api/integration/v1/flows/rest/INBOUND_EDI_VIA_REST/1.0/inbound_edi

2. Configure authorization for the request. Select HTTP Basic Auth and provide the username and password to your Oracle Integration instance.
3. Add an HTTP header with Content-Type as KEY and application/EDI-X12 as VALUE.
4. Use the sample EDI X12 purchase order provided in About Electronic Data Interchange as the request body. Copy the entire text of the EDI X12 document into the body field. If there are options for the type of request body, select Raw before you paste the EDI data.
5. Send the request from the REST client.
6. Verify the response from the integration flow.
   Check if the response status is 200 OK and the JSON is displayed as follows:

   {
     "translate_result": "Success",
     "hasError": false,
     "validationErrors": "",
     "translated_payload": "<edi-xml-document...>"
   }

   The translate_result parameter with the value Success indicates that the EDI X12 document was parsed and translated successfully.

Test Syntactical Validations

In addition to translation, the B2B action also validates the EDI data it receives and reports the errors found.

As an integration developer, when you build integrations to send EDI X12 documents to backend applications for further processing, you can check for validation errors while parsing the EDI data and handle these errors appropriately in the integration flow. For details on error handling, see Parse and Transform an Inbound EDI Message. To enable input data validations, select Yes in the Perform validations on input data? field while configuring the B2B action. See Use the B2B Action in Standalone Mode.

To test the validation feature of the B2B action, let's introduce a syntactical error in the EDI X12 purchase order document and send it to the example B2B flow through the REST client.

1. In your REST client, in line 5 of the request body (containing the EDI X12 PO data), replace USD with USD123 to make this data longer than the field allows.
2. Send the updated request from the client.
3. You'll see a response as follows:

   {
     "translate_result": "Error",
     "hasError": true,
     "validationErrors": "[1] Error code: B2B-01752 | category: data_size | message: (Severe) Element CUR02 (element id 100) has a identifier value [USD123] of length 6, which is 
     more than the maximum allowed length of 3. | segment-CUR > CUR02 (element id 100) | segment position 3 (starting with ST segment) | element position 2 | line 4 | 
     character position 7\n\n",
     "translated_payload": ...
   }

   The translate_result is now returned as Error and the syntactical error in the data is reported in the validationErrors element. This means the EDI X12 document was not successfully processed.