Edifact.Acknowledgement 1.0.0-preview.6

Edifact.Acknowledgement

Turns validation findings into a CONTRL acknowledgement, mapping each finding onto the syntax error code ISO 9735 defines for it.

A CONTRL is what you send back to say received, and here is what was wrong with it. This package takes a ValidationReport from Edifact.Validation and writes one, in syntax version 3 or version 4. It does not decide policy — whether to acknowledge at all, whether a warning is worth reporting — and it does not send anything.

Install

dotnet add package Edifact.Acknowledgement --prerelease

net8.0 and net10.0, no external dependencies. It brings Edifact.Validation and everything below it with it.

You supply the directory

No directory data ships in this package. A compiled pack is a derivative of the UN Directory, and shipping one would make every consumer a redistributor of it. Download a release from UNECE (https://unece.org/trade/uncefact/unedifact/download) and ingest it once:

dotnet tool install --global Edifact.Cli --prerelease
edifact ingest ~/Downloads/D96A --out ~/edifact/packs/compiled

That writes the pack to ~/edifact/packs/compiled/untdid-d96a, and puts the four ISO 9735 syntax definitions in ~/edifact/packs/syntax beside it. Two of those four are the CONTRL message itself, transcribed once per syntax version because no ingestion can produce it. Files already in that directory are left alone.

Use it

using Edifact.Acknowledgement;
using Edifact.Schema.Serialization;
using Edifact.Validation;

var syntax = new SyntaxPackSet("/home/me/edifact/packs/syntax");
var pack = PackReader.Read("/home/me/edifact/packs/compiled/untdid-d96a", syntax.For);

var report = new EdifactValidator(pack, syntax.For).Validate(File.ReadAllText("invoice.edi"));

var contrl = ContrlGenerator.Generate(
    report,
    // The version the subject interchange was actually read under, not the pack's.
    syntax.For(report.Syntax),
    new ContrlOptions(Reference: "ACK00042", PreparedAt: DateTimeOffset.UtcNow));

File.WriteAllText("ack.edi", contrl.ToInterchange());

ContrlOptions takes the acknowledgement's own interchange reference and its preparation time — supplied rather than read from the clock, so that generating the same acknowledgement twice produces the same characters.

Generate throws ArgumentException when the syntax version has no CONTRL definitions. That is missing configuration rather than bad input: no interchange can cause it, and the fix is a contrl-v3.json or contrl-v4.json that is not there.

What is in the acknowledgement

Every finding already carries the 1-based segment, data element and component positions a CONTRL is written in, so nothing is recomputed here. Interchange-level and message-level errors go where ISO 9735 says they go; a UCI reports the interchange, segment group 1 covers messages sent outside a functional group and segment group 3 covers the ones inside.

The acknowledgement is written with the library's own writer and holds to the same property everything else does: a generated CONTRL is read back with the library's own tokenizer and validated against the syntax pack that defines it. An acknowledgement this library cannot itself read would not be an acknowledgement.

Where this sits

Edifact.Acknowledgement → Edifact.Validation → Edifact.Overlays, Edifact.Structure, Edifact.Schema, Edifact.Core.

Full documentation: https://github.com/101-semaphore/EDIFACT.

Licence

Apache-2.0. See the NOTICE in this package for what the wider project is derived from and under what terms.