Skip to content

Commit

Permalink
Merge pull request #8242 from praneesha/fix-edi-page-issues
Browse files Browse the repository at this point in the history 
Fix the issues of the EDI Tool learn page
  • Loading branch information
@sm1990
sm1990 authored Nov 14, 2023
2 parents bdda8b5 + 82b9279 commit f1f5660
Showing 1 changed file with 96 additions and 118 deletions.
214 changes: 96 additions & 118 deletions swan-lake/integration-tools/edi-tool.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -138,7 +138,7 @@ Follow the steps below to try out an example of generating Ballerina code from a

```ballerina
import ballerina/io;
public function main() returns error? {
string ediText = check io:fileReadString("resources/edi-sample.edi");
SimpleOrder newOrder = check hmartOrder:fromEdiString(ediText);
Expand All @@ -148,22 +148,23 @@ Follow the steps below to try out an example of generating Ballerina code from a

4. Use the generated `toEdiString` function to serialize the `SimpleOrder` records into EDI text, as shown below.

```ballerina
import test_edi.hmartOrder;
import ballerina/io;
```ballerina
import test_edi.hmartOrder;
public function main() returns error? {
hmartOrder:SimpleOrder salesOrder = {header: {orderId: "ORDER_200", organization: "HMart", date: "17-05-2023"}};
salesOrder.items.push({item: "A680", quantity: 15});
salesOrder.items.push({item: "A530", quantity: 2});
salesOrder.items.push({item: "A500", quantity: 4});
import ballerina/io;
string orderEDI = check hmartOrder:toEdiString(salesOrder);
io:println (orderEDI);
}
```
public function main() returns error? {
hmartOrder:SimpleOrder salesOrder = {header: {orderId: "ORDER_200", organization: "HMart", date: "17-05-2023"}};
salesOrder.items.push({item: "A680", quantity: 15});
salesOrder.items.push({item: "A530", quantity: 2});
salesOrder.items.push({item: "A500", quantity: 4});
string orderEDI = check hmartOrder:toEdiString(salesOrder);
io:println(orderEDI);
}
```

Below is the EDI document generated as the output of the above Ballerina code that can be parsed using the above schema.
Below is the EDI document that gets generated as the output of the above Ballerina code that can be parsed using the above schema.

```
HDRORDER_200HMart17-05-2023~
Expand All @@ -174,123 +175,100 @@ Below is the EDI document generated as the output of the above Ballerina code th

### Package generation example

Follow the steps below to try out an example package generation use case of the EDI tool.

#### Clone the sample project
Below is an example of creating an EDI package and using it.

Clone the [artifacts of the example](https://github.com/ballerina-guides/integration-samples/edi_package_generation/) and extract them to a preferred location.
#### Create the package

>**Info:** The cloned directory includes the artifacts that will be required to try out this example. The `schemas` folder includes the schemas of the `EDIFACT` specifications required for an organization (`CityMart`) to work with the `INVOICE`, `ORDERS`, and `ORDRSP` EDI operations for handling purchase orders. Also, the `main.bal` file, which gets generated by the EDI tool includes the business logic/usage of the package.
If an organization (`CityMart`) needs to work with `X12 850`, `810`, `820`, and `855` for handling purchase orders, then, its integration developers can put schemas of those `X12` specifications into a folder as follows.

#### Generate the package

Follow the steps below to run the EDI tool and create the Ballerina package.

1. Navigate to the `edi_package_generation` directory.

2. Run the tool with the [required arguments](#command-options) to generate the package.

>**Note:** This example uses the EDI schema files of the [`edi_package_generation` example](https://github.com/ballerina-guides/integration-samples/edi_package_generation/) to generate the package.


```
$ bal edi libgen -O citymart -n porder -s CityMart/schemas -o CityMart/lib
```

The generated Ballerina package will be, as shown below.
```
|-- CityMart
|--lib
|--schemas
|--850.json
|--810.json
|--820.json
|--855.json
```

>**Info:** The code for each EDI schema is generated into a separate module to prevent possible conflicts.
Execute the `libgen` command to generate a Ballerina package, as shown below.

```
|-- CityMart
|--lib
|--porder
| |--modules
| | |--m850
| | | |--G_850.bal
| | | |--transformer.bal
| | |--m810
| | | |--G_810.bal
| | | |--transformer.bal
| | |--m820
| | | |--G_820.bal
| | | |--transformer.bal
| | |--m855
| | |--G_855.bal
| | |--transformer.bal
| |--Ballerina.toml
| |--Module.md
| |--Package.md
| |--porder.bal
| |--rest_connector.bal
|
|--schemas
|--850.json
|--810.json
|--820.json
|--855.json
```

3. Build the generated package.
```
$ bal edi libgen -O citymart -n porder -s CityMart/schemas -o CityMart/lib
```

```
$ cd edi_package_generation
$ bal pack
```
The generated Ballerina package will be, as shown below.

4. Push it to a repository.
```
|-- CityMart
|--lib
|--porder
| |--modules
| | |--m850
| | | |--G_850.bal
| | | |--transformer.bal
| | |--m810
| | | |--G_810.bal
| | | |--transformer.bal
| | |--m820
| | | |--G_820.bal
| | | |--transformer.bal
| | |--m855
| | |--G_855.bal
| | |--transformer.bal
| |--Ballerina.toml
| |--Module.md
| |--Package.md
| |--porder.bal
| |--rest_connector.bal
|
|--schemas
|--850.json
|--810.json
|--820.json
|--855.json
```

>**Tip:** You can push either to the local repository or the remote repository in Ballerina Central.
As seen in the above project structure, the 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 [Ballerina Central](https://central.ballerina.io/) using the `bal push` command.

```````
$ bal push --repository local
````
Then, any Ballerina project can import this package and use it to work with the EDI files related to purchase orders. An example of using this package for reading an `850` file and writing an `855` file is shown below.

#### Use the generated package
```ballerina
import ballerina/io;
import citymart/porder.m850;
import citymart/porder.m855;
public function main() returns error? {
string orderText = check io:fileReadString("orders/d15_05_2023/order10.edi");
m850:Purchase_Order purchaseOrder = check m850:fromEdiString(orderText);
...
m855:Purchase_Order_Acknowledgement orderAck = {...};
string orderAckText = check m855:toEdiString(orderAck);
check io:fileWriteString("acks/d15_05_2023/ack10.edi", orderAckText);
}
```
It is quite common for different trading partners to use variations of the 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 a particular partner.

Follow the steps below to use the generated package by running the cloned Ballerina project.
>**Info:** Now, any Ballerina project can import this package and use it to work with the EDI files related to purchase orders. An example of using this package for reading an `ORDERS` file and writing an `INVOIC` file is shown below.

1. Navigate to the `edi_package-generation` directory.

>**Info:** You can change the dependency (name and version) of the generated package in the `Ballerina.toml` file of this cloned Ballerina project directory as preferred.
You can convert `X12 850` EDI text to JSON using a cURL command, as shown below.


2. Run the cloned Ballerina project and validate the output.

```
$ bal run
Compiling source
healthcare_samples/carinbb_ballerina:1.0.0
Running executable
```

3. Invoke the API to try it out.

>**Info:** You can convert `X12 850` EDI text to JSON using a cURL command, as shown below.

```
$curl --request POST \
--url http://localhost:9090/porderParser/edis/850 \
--header 'Content-Type: text/plain' \
--data 'ST*834*12345*005010X220A1~
BGN*00*12456*20020601*1200****~
REF*38*ABCD012354~
AMT*cc payment*467.34*~
N1*P5**FI*999888777~
N1*IN**FI*654456654~
INS*Y*18*025**A***FT~
REF*0F*202443307~
REF*1L*123456001~
NM1*IL*1*SMITH*WILLIAM****ZZ*202443307~
HD*025**DEN~
DTP*348*D8*20020701~
SE*12*12345~'
```
```
$curl --request POST \
--url http://localhost:9090/porderParser/edis/850 \
--header 'Content-Type: text/plain' \
--data 'ST*834*12345*005010X220A1~
BGN*00*12456*20020601*1200****~
REF*38*ABCD012354~
AMT*cc payment*467.34*~
N1*P5**FI*999888777~
N1*IN**FI*654456654~
INS*Y*18*025**A***FT~
REF*0F*202443307~
REF*1L*123456001~
NM1*IL*1*SMITH*WILLIAM****ZZ*202443307~
HD*025**DEN~
DTP*348*D8*20020701~
SE*12*12345~'
```

The above REST call will return a JSON response, as shown below.

Expand Down Expand Up @@ -418,4 +396,4 @@ The above REST call will return a JSON response, as shown below.

The EDI package generated above can also be compiled into a JAR file (using the `bal build` command) and executed 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.

For example, the `citymart` package generated above can be built and executed as a JAR file. Once executed, it will expose a REST service to work with the `INVOICE`, `ORDERS`, and `ORDRSP` files.
For example, the `citymart` package generated above 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.

0 comments on commit f1f5660

Please sign in to comment.