Skip to content

Commit

Permalink
Merge pull request #8976 from RDPerera/edi-tool-doc-fix
Browse files Browse the repository at this point in the history 
Revise the EDI Tools Documentation
  • Loading branch information
@sm1990
sm1990 committed May 3, 2024
2 parents 1bd1b0a + a0beaeb commit 9b9c3f3
Showing 1 changed file with 31 additions and 31 deletions.
62 changes: 31 additions & 31 deletions swan-lake/integration-tools/edi-tool.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,17 +18,17 @@ $ bal tool pull edi

## Usage

The tool supports three main usages as follows.
The tool supports three main usages, as follows:

- [**Code generation**](#code-generation): Generate Ballerina records and parser functions for a given EDI schema.
- [**Library generation**](#library-generation): Generates Ballerina records, parser functions, utility methods, and a REST connector for a given collection of EDI schemas and organizes those as a Ballerina library
- [**Package generation**](#package-generation): Generates Ballerina records, parser functions, utility methods, and a REST connector for a given collection of EDI schemas and organizes those as a Ballerina package.
- [**Schema conversion**](#schema-conversion): Convert various EDI schema formats to Ballerina EDI schema format.

### Define EDI schema
### Define the EDI schema

Prior to utilizing the EDI Tools, it is crucial to define the structure of the EDI data meant for import. Developers have the option to utilize the [Ballerina EDI Schema Specification](https://github.com/ballerina-platform/module-ballerina-edi/blob/main/docs/specs/SchemaSpecification.md) for guidance. This specification outlines the essential components required to describe an EDI schema, encompassing attributes such as name, delimiters, segments, field definitions, components, sub-components, and additional configuration options.
Prior to utilizing the EDI tools, it is crucial to define the structure of the EDI data meant for import. Developers have the option to utilize the [Ballerina EDI Schema Specification](https://github.com/ballerina-platform/module-ballerina-edi/blob/main/docs/specs/SchemaSpecification.md) for guidance. This specification outlines the essential components required to describe an EDI schema, encompassing attributes such as name, delimiters, segments, field definitions, components, sub-components, and additional configuration options.

As an illustrative example, consider the following EDI schema definition for a _simple order_, assumed to be stored as "schema.json":
As an illustrative example, consider the following EDI schema definition for a `simple order`, assumed to be stored as `schema.json`:

```json
{
Expand All @@ -51,9 +51,9 @@ As an illustrative example, consider the following EDI schema definition for a _
}
```

This schema can be employed to parse EDI documents featuring one HDR segment, mapped to the _header_, and any number of ITM segments, mapped to _items_. The HDR segment incorporates three _fields_, corresponding to _orderId_, _organization_, and _date_. Each ITM segment comprises two fields, mapped to _item_ and _quantity_.
This schema can be employed to parse EDI documents featuring one HDR segment, mapped to the `header`, and any number of ITM segments, mapped to `items`. The HDR segment incorporates three `fields`, corresponding to _orderId_, _organization_, and _date_. Each ITM segment comprises two fields, mapped to _item_ and _quantity_.

Below is an example of an EDI document that can be parsed using the aforementioned schema. Let's assume that the following EDI information is saved in a file named 'sample.edi':
Below is an example of an EDI document that can be parsed using the aforementioned schema. Let's assume that the following EDI information is saved in a file named `sample.edi`:

```
HDR*ORDER_1201*ABC_Store*2008-01-01~
Expand All @@ -63,7 +63,7 @@ ITM*D-10*58~
ITM*K-80*250~
ITM*T-46*28~
```
If you already have existing X12,EDIFACT or ESL schema file you can convert it to the Ballerina schema
If you already have an existing X12, EDIFACT, or ESL schema file, you can convert it to the Ballerina EDI schema using the EDI tool's [schema-conversion](#schema-conversion) capabilities.

## Code generation

Expand All @@ -73,7 +73,7 @@ The below command can be used to generate typed Ballerina records and parser fun
$ bal edi codegen -i <input schema path> -o <output path>
```

The above command generates all Ballerina records and parser functions required for working with data in the given EDI schema and writes those into the file specified in the `output path`. The generated parser function (i.e. `fromEdiString(...)`) can read EDI text files into generated records, which can be accessed from Ballerina code similar to accessing any other Ballerina record. Similarly, generated serialization function (i.e. `toEdiString(...)`) can serialize Generated Ballerina records into EDI text.
The above command generates all Ballerina records and parser functions required for working with data in the given EDI schema and writes those into the file specified in the `output path`. The generated parser function (i.e., `fromEdiString(...)`) can read EDI text files into generated records, which can be accessed from the Ballerina code, similar to accessing any other Ballerina record. Similarly, the generated serialization function (i.e., `toEdiString(...)`) can serialize generated Ballerina records into EDI text.

### `codegen` command options

Expand All @@ -84,7 +84,7 @@ The above command generates all Ballerina records and parser functions required

### Code generation example

Create a new Ballerina project named `sample` and create a module named `orders` inside that project by using the below commands
Create a new Ballerina project named `sample` and create a module named `orders` inside that project by using the below commands.

```
$ bal new sample
Expand All @@ -110,7 +110,7 @@ Create a new folder named resources in the root of the project and copy the `sch
└── schema.json
```

Ballerina records for the EDI schema in the `resources/schema.json` can be generated as follows (generated Ballerina records will be saved in `modules/order/records.bal`).
Ballerina records for the EDI schema in `resources/schema.json` can be generated as follows (generated Ballerina records will be saved in `modules/order/records.bal`).

Run the below command from the project root directory to generate the Ballerina parser for the above schema.

Expand Down Expand Up @@ -142,7 +142,7 @@ public type SimpleOrder record {|

#### Reading EDI files

The generated `fromEdiString` function can be used to read EDI text files into the generated Ballerina record as shown below. Note that any data item in the EDI can be accessed using the record's fields, as shown in the example code.
The generated `fromEdiString` function can be used to read EDI text files into the generated Ballerina record, as shown below. Note that any data item in the EDI can be accessed using the record's fields, as shown in the example code.

```ballerina
import ballerina/io;
Expand All @@ -157,7 +157,7 @@ public function main() returns error? {

#### Writing EDI files

The generated `toEdiString` function can be used to serialize `SimpleOrder` records into EDI text as shown below:
The generated `toEdiString` function can be used to serialize `SimpleOrder` records into EDI text, as shown below:

```ballerina
import ballerina/io;
Expand All @@ -172,29 +172,29 @@ public function main() returns error? {
}
```

## Library generation
## Package generation

Usually, organizations have to work with many EDI formats, and integration developers need to have a convenient way to work on EDI data with minimum effort. Ballerina EDI libraries facilitate this by allowing organizations to pack all EDI processing codes for their EDI collections into an importable library. Therefore, integration developers can simply import those libraries and convert EDI messages into Ballerina records in a single line of code.
Usually, organizations have to work with many EDI formats, and integration developers need to have a convenient way to work on EDI data with minimum effort. Ballerina EDI libraries facilitate this by allowing organizations to pack all EDI processing codes for their EDI collections into an importable package. Therefore, integration developers can simply import those libraries and convert EDI messages into Ballerina records in a single line of code.

The below command can be used to generate Ballerina records, parser and util functions, and a REST connector for a given collection of EDI schemas organized into a Ballerina package:

```
$ bal edi libgen -p <package name> -i <input schema folder> -o <output folder>
```

The Ballerina library project will be generated in the output folder. This library can be built and published by issuing "bal pack" and "bal push" commands from the output folder. Then the generated library can be imported into any Ballerina project and generated utility functions of the library can be invoked to parse EDI messages into Ballerina records.
The Ballerina package will be generated in the output folder. This package can be built and published by issuing `bal pack` and `bal push` commands from the output folder. Then, the generated package can be imported into any Ballerina project, and the generated utility functions of the package can be invoked to parse EDI messages into Ballerina records.

### `libgen` command options

| Command option | Description | Mandatory/Optional |
|-----------------|-------------------------------------------------------|--------------------|
| `-p, --package` | Package name (organization-name/library-name). | Mandatory |
| `-p, --package` | Package name (organization-name/package-name). | Mandatory |
| `-i, --input` | Path to the folder containing EDI schemas. | Mandatory |
| `-o, --output` | Path to the folder where libraries will be generated. | Mandatory |

### Library generation example
### Package generation example

let's assume that an organization named "CityMart" needs to work with X12 850, 810, 820, and 855 to handle purchase orders. CityMart's integration developers can put schemas of those X12 specifications into a folder as follows:
Let's assume that an organization named "CityMart" needs to work with X12 850, 810, 820, and 855 to handle purchase orders. CityMart's integration developers can put schemas of those X12 specifications into a folder as follows:

```
|-- CityMart
Expand All @@ -206,13 +206,13 @@ let's assume that an organization named "CityMart" needs to work with X12 850, 8
|--855.json
```

Then the libgen command can be used to generate a Ballerina library as shown below:
Then, the `libgen` command can be used to generate a Ballerina package as shown below:

```
$ bal edi libgen -p citymart/porder -i CityMart/schemas -o CityMart/lib
```

The generated Ballerina library will look like below:
The generated Ballerina package will look like below:

```
|-- CityMart
Expand Down Expand Up @@ -244,7 +244,7 @@ The generated Ballerina library will look like below:
|--855.json
```

As seen in the above project structure, code for each EDI schema is generated into a separate module, in order to prevent possible conflicts. Now it is possible to build the above project using the `bal pack` command and publish it into the central repository using the `bal push` command. Then any Ballerina project can import this package and use it to work with purchase order-related EDI files. An example of using this library for reading an 850 file and writing an 855 file is shown below:
As seen in the above project structure, code for each EDI schema is generated into a separate module, to prevent possible conflicts. Now it is possible to build the above project using the `bal pack` command and publish it into the central repository using the `bal push` command. Then any Ballerina project can import this package and use it to work with purchase order-related EDI files. An example of using this package for reading an 850 file and writing an 855 file is shown below:

```ballerina
import ballerina/io;
Expand All @@ -261,13 +261,13 @@ public function main() returns error? {
}
```

It is quite common for different trading partners to use variations of standard EDI formats. In such cases, it is possible to create partner-specific schemas and generate a partner-specific Ballerina library for processing interactions with the particular partner.
It is quite common for different trading partners to use variations of standard EDI formats. In such cases, it is possible to create partner-specific schemas and generate a partner-specific Ballerina package for processing interactions with the particular partner.

#### Using generated EDI libraries as standalone REST services

EDI libraries generated in the previous step can also be compiled to a jar file (using the `bal build` command) and executed(using the `bal run` command) as a standalone Ballerina service that processes EDI files via a REST interface. This is useful for microservices environments where the EDI processing functionality can be deployed as a separate microservice.
EDI libraries generated in the previous step can also be compiled into a jar file (using the `bal build` command) and executed (using the `bal run` command) as a standalone Ballerina service that processes EDI files via a REST interface. This is useful for microservice environments where the EDI processing functionality can be deployed as a separate microservice.

For example, "citymart" library generated in the above step can be built and executed as a jar file. Once executed, it will expose a REST service to work with X12 850, 810, 820, and 855 files. Converting of X12 850 EDI text to JSON using the REST service is shown below:
For example, the citymart package generated in the above step can be built and executed as a jar file. Once executed, it will expose a REST service to work with X12 850, 810, 820, and 855 files. The conversion of X12 850 EDI text to JSON using the REST service is shown below:

```
$ curl --request POST \
Expand Down Expand Up @@ -321,11 +321,11 @@ The above REST call will return a JSON response like the below:

## Schema conversion

Instead of writing Ballerina EDI schema from scratch, The Ballerina EDI tool also supports converting various EDI schema formats to Ballerina EDI schema format.
Instead of writing the Ballerina EDI schema from scratch, the Ballerina EDI tool also supports converting various EDI schema formats to the Ballerina EDI schema format.

### X12 schema to Ballerina EDI schema
### X12 schema to the Ballerina EDI schema

X12, short for ANSI ASC X12, is a standard for electronic data interchange (EDI) in the United States. It defines the structure and format of business documents such as purchase orders, invoices, and shipping notices, allowing for seamless communication between different computer systems. X12 standards cover a wide range of industries, including healthcare, finance, retail, and manufacturing.
X12, short for ANSI ASC X12, is a standard for electronic data interchange (EDI) in the United States. It defines the structure and format of business documents such as `purchase orders`, `invoices`, and `shipping notices`, allowing for seamless communication between different computer systems. X12 standards cover a wide range of industries, including healthcare, finance, retail, and manufacturing.

The below command can be used to convert the X12 schema to the Ballerina EDI schema:

Expand All @@ -348,7 +348,7 @@ Example:
$ bal edi convertX12Schema -i input/schema.xsd -o output/schema.json
```

### EDIFACT schema to Ballerina EDI schema
### EDIFACT schema to the Ballerina EDI schema

EDIFACT, which stands for Electronic Data Interchange For Administration, Commerce, and Transport, is an international EDI standard developed by the United Nations. It's widely used in Europe and many other parts of the world. EDIFACT provides a common syntax for exchanging business documents electronically between trading partners, facilitating global trade and improving efficiency in supply chain management.

Expand All @@ -373,9 +373,9 @@ $ bal edi convertEdifactSchema -v d03a -t ORDERS -o output/schema.json

### ESL to Ballerina EDI schema

ESL, or Electronic Shelf Labeling, is a technology used in retail stores to display product pricing and information electronically. Instead of traditional paper price tags, ESL systems use digital displays that can be updated remotely, allowing retailers to change prices in real time and automate pricing strategies.
ESL, or Electronic Shelf Labeling, is a technology used in retail stores to display product pricing and information electronically. Instead of traditional paper price tags, ESL systems use digital displays that can be updated remotely, allowing retailers to change prices in real-time and automate pricing strategies.

The below command can be used to convert ESL schema to Ballerina EDI schema:
The below command can be used to convert the ESL schema to the Ballerina EDI schema:

```
$ bal edi convertESL -b <segment definitions file path> -i <input ESL schema file/folder> -o <output file/folder>
Expand Down

0 comments on commit 9b9c3f3

Please sign in to comment.