Using EDIFACT with Choreo

Introduction

Electronic data interchange (EDI) revolutionizes business communication by enabling standardized structured data exchange between enterprises. Electronic data interchange for administration, commerce, and transport (EDIFACT) stands out as a widely adopted international EDI standard developed by the United Nations. In B2B integration scenarios, companies often use different data formats, such as EDIFACT, JSON, XML, etc. This necessitates a seamless bridge to facilitate smooth communication between trading partners.

Ballerina emerges as the solution to handle EDIFACT data with minimum effort. With its EDIFACT modules, Ballerina allows parsing EDI messages without manual schema creation. 

This guide provides a simple B2B integration scenario between two businesses (Foo Corp and Bar Industries). This scenario uses the edifact.d03a.supplychain module. 

Prerequisites

1. Fork the Choreo samples repository, which contains the edifact-order-service sample Ballerina project required for this guide.
2. If you are signing in to the Choreo Console for the first time, create an organization as follows:
   1. Go to https://console.choreo.dev/, and sign in using your Google, GitHub, or Microsoft account.
   2. Enter a unique organization name—e.g., Stark Industries.
   3. Read and accept the privacy policy and terms of use.
   4. Click Create, and open the Project Home page of the default project created for you.

Understanding the Business Scenario

Figure 1: Overview of the business scenario

Foo Corp

Foo Corp is a company that utilizes the EDIFACT format for its B2B communication. They will interact with Bar Industries by sending EDI messages (ORDERS) via HTTP requests.

Bar Industries

Bar Industries has a backend that expects a JSON input and responds with a JSON output (JSON backend). For this tutorial, this backend is already deployed to a public URL, and implementing it is beyond the scope of our current focus. Bar Industries exposes its JSON backend via an integration service. 

Integration Flow

• Foo Corp sends an HTTP POST request containing an EDIFACT message (ORDERS) to the integration service.
• The integration service parses the incoming EDIFACT message, transforming it into a JSON object that the JSON backend can process. It calls the JSON backend with the data obtained from the EDIFACT message.
• The JSON backend processes the data and responds with a JSON output.
• The integration service maps the response from the JSON backend back into an EDIFACT message (ORDRSP) and responds to Foo Corp with the EDIFACT message (ORDRSP).

Understand the Sample Code

Figure 2. Flowchart of the integration service

The Choreo samples repository has the Ballerina implementation of the mentioned scenario in this directory:edifact-order-service. The following is a brief explanation of the code inmain.bal.

1. Service Endpoint and Resource Function: 

The service is defined to listen on the path / of the HTTP endpoint on port 8090. It expects a message type parameter in the URL to identify the type of EDIFACT message.

  
service / on new http:Listener(8090) {
resource function post [string msgTypeId](http:Request req) returns string|error|http:Response {
...
}
}
        
        

2. Receiving and Validating the EDIFACT Message:

This section extracts the EDIFACT message from the request payload and validates the message type.

  
string ediMsg = check req.getTextPayload();
MsgType? msgType = msgTypes[msgTypeId];
if msgType is () {
// Invalid message type
...
}
    
    

3. Transforming and Mapping the EDIFACT Message:

The EDIFACT message is parsed using a Ballerina EDIFACT module, and its data is extracted for further processing.

  
mORDERS:EDI_ORDERS_root purchaseOrder = check mORDERS:fromEdiString(ediMsg);
// Extracting relevant data from the EDI message
...

4. Mapping extracted data:

The extracted data from the EDIFACT message is mapped to the request data model of Bar Industries.

  
SupplierRequest supplierRequest = {
buyerName: buyerName,
date: orderDate,
productIdentifier: productIdentifier,
productQty: productQty,
msgTypes: msgTypeId
};

5. Communicating with the JSON backend of Bar Industries:

The integration service initiates an HTTP POST request to the JSON backend with the transformed JSON data obtained from the EDIFACT message.

  
http:Client supplierService = check new ("https://samples.choreoapps.dev/supplier");
SupplierResponse supplierResponse = check supplierService->post("/", supplierRequestJson);

6. Transforming and Mapping Bar Industries' JSON backend Response:

The response from the JSON backend is processed and mapped back into an EDIFACT response (ORDRSP).

  
mORDRSP:EDI_ORDRSP_root responseEdiMsg = { ... }
if (supplierResponse.isConfirmed == true) {
// Order is accepted
...
} else {
// Order is rejected
...
}

7. Preparing the EDI Response and Sending it Back:

The integration service converts the EDIFACT response into a string and returns it to Foo Corp.

  
string responseEDI = check mORDRSP:toEdiString(responseEdiMsg);
return responseEDI;

Deploy an Integration Service in Choreo and Test it

Step 1: Create a component

Let's create a Ballerina service component by following these steps:

1. Go to https://console.choreo.dev/ and sign in. This opens the home page of the default project.
2. Click on the Service card.
3. Enter a unique name and description for the service. For this guide, enter the following values:

   Field	Value
   Component Name	EDIFACT Order Service
   Description	Integration Service of Bar Industries

4. To allow Choreo to connect to your GitHub account, click Authorize with GitHub.
5. If you still need to connect your GitHub repository to Choreo, enter your GitHub credentials, and select the repository you forked in the prerequisites section to install the Choreo GitHub App.
6. Enter the following information:

   Field	Description
   GitHub Account	Your account
   GitHub Repository	choreo-samples
   Branch	main
   Buildpack	Ballerina
   Ballerina Project Directory	edifact-order-service

7. Click Create. Once the component creation is complete, you will see the component overview page.

You have successfully created a Service component that acts as the integration service in our scenario.

Step 2: Build and Deploy

Now that we have connected the source repository, it's time to build and deploy the service. Follow the steps below:

1. In the left navigation, click Deploy and navigate to the Deploy page.
2. On the Deploy page, click Configure and Deploy.
3. In the Endpoints pane that opens on the right, click the edit icon to edit the Endpoint.
4. Under Network Visibility, select Public and click Update.
5. Click Deploy.

Once you have successfully deployed your service, you can test, manage, and observe your component.

Step 3: Testing

1. Click Test in the left navigation menu and then click Console. This opens the OpenAPI Console pane.
2. Expand the POST resource.
3. Click Try it out.
4. In the msgTypeId (path) field, enter “ORDERS”.
5. Test Scenario 1: Placing an Accepted Order
   1. In the Request body field, enter the following EDIFACT message, representing an order for ten pieces of product "PRD1234567890." 

        
      BGM+380+4467862+9'
      DTM+137:20230719:102'
      RFF+ON:123456'
      NAD+BY+WALMARTUS::92++WALMART US'
      NAD+SU+GLAXOSMITHK::92++GLAXOSMITHK'
      LIN+1++PRD1234567890:EN'
      QTY+47:10:PCE'
      MOA+203:150'
      ALC+C+AAB'
      MOA+8:15'
      TAX+7+VAT+++:::20'
      MOA+124:30'
      UNS+S'
      MOA+77:195'
                       

   2. Click Execute. The response in the Response body will contain the following EDIFACT message, indicating that Bar Industries has accepted the order for product "PRD1234567890."

        
      BGM+380+4467862+9'
      DTM+137:20230719:102'
      RFF+ON:123456'
      LIN+1++PRD1234567890:EN'
      QTY+47:10:PCE'
      FTX+AAE+++Order is accepted'
      UNS'
                       

6. Test Scenario 2: Placing a Rejected Order
   1. In the Request body field, enter the following EDIFACT message, representing an order for ten pieces of product "PRD1234567900."

        
      BGM+380+4467862+9'
      DTM+137:20230719:102'
      RFF+ON:123456'
      NAD+BY+WALMARTUS::92++WALMART US'
      NAD+SU+GLAXOSMITHK::92++GLAXOSMITHK'
      LIN+1++PRD1234567890:EN'
      QTY+47:10:PCE'
      MOA+203:150'
      ALC+C+AAB'
      MOA+8:15'
      TAX+7+VAT+++:::20'
      MOA+124:30'
      UNS+S'
      MOA+77:195'
                           

   2. Click Execute. The response in the Response body will contain the following EDIFACT message, indicating that Bar Industries has rejected the order for product "PRD1234567900."

        
      BGM+380+4467862+9'
      DTM+137:20230719:102'
      RFF+ON:123456'
      LIN+1++PRD1234567900:EN'
      FTX+AAE+++Order is rejected'
      UNS'
                           

Step 4: Observe, Manage, and More

In addition to Deploy and Test, Choreo provides advanced capabilities for observing and managing services. 

If you want to view Kubernetes-level insights for a more detailed diagnosis of this Ballerina service, see Choreo's DevOps capabilities.

Conclusion

In this tutorial, we explored how to use EDIFACT with Choreo, leveraging Ballerina's EDIFACT modules to facilitate seamless B2B communication between two businesses, Foo Corp and Bar Industries. By transforming EDI messages into JSON and vice versa, the integration service acted as a bridge, allowing businesses with different data formats to interact effortlessly. We tested the scenarios, demonstrating the smooth integration flow, and highlighted Choreo's capabilities for observing and managing services.