Add a how-to guide for processing inbound EDI purchase orders

[niveathika]

Purpose

Part of the EDI documentation pass for the envelope-aware API (ballerina-spec#1441).

The EDI pages explain the tool and the API, but nothing walks through a whole flow end to end. This adds a how-to guide that does, in the order the work actually happens.

The guide

en/docs/guides/howtoguides/edi-purchase-order-processing.md, patterned on the SAP B1 how-to guide (Visual Designer / Ballerina Code tabs, screenshots, prerequisites block):

• Part 1 — identify the trading partner. edi:edifactHeadersFromEdiFile reads the UNB envelope with no schema and only the first 512 characters of the file, and the flow stops if the sender is not the expected partner. This part works before any code is generated.
• Part 2 — parse the orders. Generate the schema from the D03A directory, adjust it for the partner's deviations, generate the library, then interchangeFromEdiString with the fail-safe per-transaction body: two orders processed, one malformed message quarantined with its parse error.

The narrative is deliberately the one a real user follows — convert the spec, edit the schema, generate the library, add it to the project — with a note up front that a prebuilt ballerinax/edifact.d03a.* package can be imported instead when it fits as-is, and a note that X12 specifications are licensed from ASC X12 with a pointer to contact us.

The prebuilt-package note originally said the schema generation could be skipped entirely for standard D03A types. That is wrong for this guide's flow: The prebuilt ballerinax/edifact.d03a.* packages are at 0.9.0 and predate the envelope-aware API: their schemas carry ignoreSegments: ["UNA", "UNB", "UNH", "UNT", "UNZ"] and no envelope, so fromEdiString parses a single message body and discards the interchange. Checked against Central: a two-message interchange fails outright. The note now states the limitation, since identifying the partner from UNB and splitting a batch are exactly what the guide does.

Verification

• The finished workspace is published as a sample: Add the EDI purchase order processing sample integration-samples#161. Everything in the guide comes from that project actually running — the sample interchange, the schema edit, the log output, and all three screenshots.
• The screenshots are the sample opened in the WSO2 Integrator Visual Designer (code-server): the part 1 flow, the part 2 flow, and the terminal after Run Integration.
• npm run build on this branch alone reports one broken anchor, /develop/transform/edi#adjusting-a-schema-for-a-trading-partner. That heading is added by Align EDI docs with the envelope-aware module and tool #551, so the anchor resolves once Align EDI docs with the envelope-aware module and tool #551 merges — building this branch merged with Align EDI docs with the envelope-aware module and tool #551 reports no broken links and no broken anchors other than the pre-existing one on /guides/patterns/message-mapper.
• A broken link to develop/integration-artifacts/service.md was also caught and fixed: integration-artifacts/service is a directory of protocol pages with no service.md. The What's next bullet now points at integration-artifacts/file/local-files.md and integration-artifacts/file/ftp-sftp.md.

Depends on

• Align EDI docs with the envelope-aware module and tool #551 for the Adjusting a schema for a trading partner section this guide links to. Merge that first.
• Add the EDI purchase order processing sample integration-samples#161 for the Sample project link.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 5897cc3c-f81f-4c02-810e-035b4931c337

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}