Streamlining B2B Connections: EDI Processing with Ballerina

This article was written using Ballerina Swan Lake Update 8.0 (2201.8.0)

Introduction

Electronic Data Interchange (EDI) has revolutionized the way businesses exchange information, enabling seamless communication and integration among trading partners. In a previous blog, we explored the fundamentals of EDI and its importance in modern business landscapes. (Check out the previous blog: An Introduction to EDI: Streamlining Connections in the B2B Landscape) In this blog, we’ll dive deeper into how Ballerina can optimize EDI processing for B2B communications, showcasing its capabilities through practical examples and step-by-step guides to creating and managing EDI schemas efficiently.

EDI fundamentally enables the electronic transfer of business documents in a uniform format. This means each document, known as a transaction, is organized according to specific rules, consisting of predefined sections and individual pieces of data.

For example, an EDI file used for invoices can contain segments such as HDR (header) (containing information about the invoice), DTL (detail) (listing the items included in the invoice), and SUM (summary) (providing totals and other summary data). Each segment comprises data elements that convey specific information, such as item codes, quantities, prices, and more.

Example EDI Invoice File:

HDR*INV-123456*2024-03-01*1500~
DTL*001*Product A*10*20~
DTL*002*Product B*5*30~
SUM*2*700~

Understanding EDI Standards:

Standards are vital in Electronic Data Interchange (EDI), ensuring smooth communication between various organizations. They define the structure, format, and rules for exchanging business documents electronically.

EDI standards, such as X12 and EDIFACT, play a crucial role in ensuring interoperability and consistency in EDI implementations across industries. Major companies, including Walmart, Amazon, Target, and IBM, rely on these standards to streamline their B2B communications.

Businesses and EDI:

Businesses across various industries rely on EDI to streamline their operations and enhance efficiency in exchanging critical business information. In a typical scenario, EDI facilitates communication between trading partners, suppliers, manufacturers, distributors, and retailers. Here’s a simplified diagram illustrating how businesses use EDI:

Ballerina for EDI Processing

Ballerina emerges as a powerful choice for EDI processing due to its built-in support for handling complex EDI structures and facilitating seamless integration with external systems. Moreover, Ballerina’s integration capabilities, flexibility, and simplicity make it an ideal language for developing data-oriented business integrations.

Creating an EDI Schema with Ballerina:

To work with EDI in Ballerina, it’s essential to define an EDI schema that describes the structure of the EDI documents. The “Ballerina EDI Schema Specification” provides comprehensive guidance on defining schemas. (Link to Schema Specification: Ballerina EDI Schema Specification)

{ 
"name": "Invoice",
 "delimiters" : {"segment" : "~", "field" : "*", "component": ":", "repetition": "^"},
 "segments" : [
 {
 "code": "HDR",
 "tag" : "header",
 "minOccurances": 1,
 "fields" : [{"tag": "invoiceNumber"}, {"tag" : "invoiceDate"}, {"tag" : "totalAmount"}]
 },
 {
 "code": "DTL",
 "tag" : "detail",
 "maxOccurances" : -1,
 "fields" : [{"tag": "itemCode"}, {"tag" : "description"}, {"tag" : "quantity", "dataType" : "int"}, {"tag" : "unitPrice", "dataType" : "decimal"}]
 },
 {
 "code": "SUM",
 "tag" : "summary",
 "minOccurances": 1,
 "fields" : [{"tag": "totalItems"}, {"tag" : "grandTotal"}]
 }
 ]
}

This schema, named “Invoice” is designed to process EDI documents related to invoices. It comprises three segments:

1. HDR Segment (Header): This segment contains the invoiceNumber, invoiceDate, and totalAmount.
2. DTL Segment (Detail): Each DTL segment represents a line item in the invoice. It includes fields for itemCode, description, quantity, and unitPrice.
3. SUM Segment (Summary): The SUM segment provides summary information for the invoice, including totalItems and grandTotal.

Example EDI Document for the schema:

HDR*INV-1234*2024-03-03*500.00~
DTL*ABC123*Product ABC*2*100.00~
DTL*DEF456*Product DEF*3*75.00~
SUM*2*325.00~

Using the Ballerina EDI Tool to create Ballerina records:

After creating the schema definition for your EDI schema we can use the Ballerina EDI Tool to create Ballerina records which help map EDI to variables. Here are the steps to use it:

• Create a Ballerina project using $ bal new your_project_name.
• Create a module for records in that project using $ bal add invoice.
• Install the Ballerina EDI Tool by executing the command: $ bal tool pull edi.

Use the bal edi codegen command to generate Ballerina records and parser functions for your schema.

eg: — bal edi codegen -i path/to/schema.json -o modules/invoices/invoice.bal

Reading and Writing EDI Files:

Once you’ve generated the necessary Ballerina records, you can easily read and write EDI files using Ballerina. Here’s a simple code snippet demonstrating how to read and write EDI files:

import ballerina/io;
import your_package_name;

public function main() returns error? {
 string ediText = check io:fileReadString("path/to/edi/file.edi");
 YourRecordType record = check your_package_name:fromEdiString(ediText);
 // Perform operations on the record
 // Write the modified record back to an EDI file
 string modifiedEdiText = check your_package_name:toEdiString(record);
 check io:fileWriteString("path/to/output/file.edi", modifiedEdiText);
}

Converting other EDI Schemas to Ballerina EDI Schemas:

If you are already following EDIFACT or X12 standards, you can convert their schemas to Ballerina EDI schemas using the Ballerina EDI Tool’s schema conversion features. For example, to convert an X12 schema to a Ballerina EDI schema, you can use the following command:

$ bal edi convertX12Schema -i input/schema.xsd -o output/schema.json

More information and supported schemas: https://github.com/ballerina-platform/edi-tools

Additionally, deploying Ballerina applications for EDI processing is made even easier with Choreo, a comprehensive platform for deploying, managing, and scaling cloud-native applications. With Choreo, businesses can seamlessly deploy their Ballerina EDI applications to the cloud, ensuring scalability, reliability, and optimal performance in real-world environments.

And there you have it — the key steps to crafting your own EDI schema and seamlessly processing EDIs with Ballerina. Happy coding!