From IPWorks EDI Translator to EDI SDK: A Migration Guide

Requirements: EDI SDK

Introduction

EDI SDK is the successor to IPWorks EDI Translator and is the recommended choice for all new EDIFACT and X12 development. Built from the ground up with a focus on those formats, it introduces a cleaner API, a typed object model for the EDI envelope (the layered structure of Interchanges, Functional Groups, and Messages that wraps the business content), and an optional code generation layer that eliminates manual segment navigation entirely. The meaningful differences from IPWorks EDI Translator are in how EDI data is exposed, how schemas are managed, and what higher-level tools are available.

Format Coverage

EDI SDK covers EDIFACT and X12, the formats that account for the vast majority of EDI traffic. TRADACOMS, HL7, VDA, and Cargo (flat-file) are not currently included; for those, IPWorks EDI Translator remains the right product. EDI SDK is in beta and format coverage may expand - contact us with any specific requirements.

The Core Architectural Shift: Accessing EDI Data

IPWorks EDI Translator: XPath-Based Navigation

In IPWorks EDI Translator, all reader components (EDIFACTReader, X12Reader, TRADACOMSReader) share a single generic base. Navigation uses XPath-style properties that are populated as each event fires during parsing:

Navigation requires tracking position manually, parsing path strings, and correlating event state to application logic.

EDI SDK: Format-Specific Components with Typed Access

EDI SDK replaces the single generic reader with format-specific components, each exposing the parsed document as a structured, indexed hierarchy. Once Parse completes, the full envelope is available through named, typed properties:

Reader.InterchangeCount         // number of interchanges
Reader.InterchangeIndex = 0     // select the first interchange
Reader.Interchange              // EDIFACTInterchange with SenderIdentification, Date, etc.
Reader.MessageCount             // number of messages in this interchange
Reader.MessageIndex = 0         // select the first message
Reader.Message                  // EDIFACTMessage with MessageType, Version, etc.
Reader.SegmentCount             // segments in this message
Reader.Segment                  // EDISegment with Tag, Path, etc.
Reader.Element[i].Value         // value of element i in the current segment

Header values are named properties on a typed object rather than positional data in an XPath string. The structure of the document is reflected directly in the API. For applications that want to go further, the EDI Objects layer (described below) eliminates index-based navigation entirely.

Readers

Loading a Schema

EDI SDK ships with human-readable XML schemas for all official EDIFACT releases, found in the install directory under /schemas/EDIFACT. For X12, a separate import tool is included to generate the equivalent schemas from X12.org source files; see Importing X12 Schemas to EDI SDK for details. Schemas are optional for parsing but required for validation and for schema-related fields like SchemaName and SchemaDesc to be populated.

LoadSchema and the ResolveSchema event work the same way in both products, supporting dynamic loading when the message type or version is not known ahead of time:

reader.OnResolveSchema += (s, e) =>
{
    string schemaPath = basePath + e.MessageVersion + ".xml";
    reader.LoadSchema(schemaPath, e.MessageType);
};

EDI SDK's LoadSchema accepts both file paths and streams directly, removing the need for a separate LoadSchemaStream overload that EDI Translator required. Building schemas from source is handled outside the component by a dedicated schema builder tool, keeping the component API focused. The resulting XML schema is then loaded via LoadSchema.

Parsing Events

The core event set is the same: Segment, ResolveSchema, StartInterchange/EndInterchange, StartFunctionalGroup/EndFunctionalGroup, and Error. EDI SDK adds more granular envelope events that reflect the format structure more precisely:

• StartMessage/EndMessage (EDIFACT)
• StartTransactionSet/EndTransactionSet (X12; EDI Translator named these StartTransaction/EndTransaction)
• StartGroup/EndGroup

Setting BuildDOM before parsing captures the document structure in memory as it is processed. When set, properties such as Message, Segment, and the indexed element collections are accessible inside event handlers as each section of the document is reached.

Header events in EDI SDK expose structured fields directly on the event arguments rather than requiring XPath reads. Checking the sender on an incoming interchange, for example, is a straightforward property comparison:

reader.OnStartInterchange += (s, e) =>
{
    if (e.SenderIdentification == trustedPartnerId)
    {
        // apply logic for trusted partner
    }
};

Validation warnings surface through the ValidateWarning event (EDI Translator used Warning and a separate ValidationError event). Errors are not stored internally and should be captured as they occur:

reader.OnValidateWarning += (s, e) =>
{
    string err = $"[{e.Position}-{e.Line},{e.Column}] {e.ErrorCode}: {e.ErrorMessage} - {e.ErrorType}";
    warnings.Add(err);
};

Reading Data After Parsing

EDI SDK provides two approaches to accessing parsed data. GetElement takes a path string and is the quickest option when the element location is known:

string element = reader.GetElement("CPSGroup[2].LINGroup[2].QTY.1.2");

Segment iteration (using SegmentIndex, ElementIndex, ComponentIndex) is better when scanning messages with variable structure or when schema metadata such as SchemaName and SchemaDesc is needed alongside values. For applications processing known message types, EDI Objects replace both approaches with strongly-typed, named properties; see the EDI Objects section below.

For a detailed walkthrough, see Getting Started with EDIFACTReader and Getting Started with X12Reader.

New Properties in EDI SDK Readers

Reader Properties Without a Direct EDI SDK Equivalent

Some EDI Translator reader properties are not present in EDI SDK. In some cases the same information is accessible through typed header objects; in others, there is no equivalent.

Translators

The translator components (EDIFACTTranslator, X12Translator) convert documents between EDI and XML format. The core API is consistent across both products: InputData/InputFile, OutputData/OutputFile, InputFormat/OutputFormat, Delimiters, Translate, LoadSchema, SetInputStream, and SetOutputStream.

Translation in EDI SDK

Validation warnings during translation use the same ValidateWarning event pattern as the reader. See Getting Started with EDIFACTTranslator and Getting Started with X12Translator for full examples.

Key Differences

File write behavior: EDI Translator's boolean Overwrite property is replaced in EDI SDK by a FileWriteMode enum that covers overwrite, append, and create behaviors more explicitly.

Output formatting: Suffix in EDI Translator is SegmentSuffix in EDI SDK.

Reset: EDI SDK adds an explicit Reset method on the translator.

Renaming rules: EDI Translator includes a renaming rule system (RenamingRule, AddRenamingRule, LoadRenamingRules, SaveRenamingRules) for remapping element names during translation. This is not available in EDI SDK.

UseSchemaName and ExportXMLSchema: Both are EDI Translator-only. Schema export in EDI SDK is handled by the external schema builder tool.

Validators

The validator components, EDIFACTValidator and X12Validator, have the same core API in both products: InputData/InputFile, ValidationErrors, Validate, LoadSchema, Reset, and SetInputStream.

Validation in EDI SDK

Set InputFile (or InputData), attach a ResolveSchema handler to load schemas dynamically, and call Validate. Warnings surface through ValidateWarning and the full results are available in ValidationErrors afterward. For many use cases the ValidateOnParse property on the reader is more convenient, running validation inline during parsing without needing a separate validator component.

For more on validation setup, see Getting Started with EDIFACTReader and Getting Started with X12Reader.

Key Differences

Delimiters: EDI SDK exposes a Delimiters property directly on the validator. EDI Translator handles delimiters through configuration.

Events during validation: EDI Translator fires the full set of reader streaming events during validation (Segment, StartInterchange, StartFunctionalGroup, etc.), which can be useful but adds complexity. EDI SDK keeps validation focused, firing only Error, ResolveSchema, and ValidateWarning, with complete results available in ValidationErrors afterward.

Schema methods: EDI Translator includes CompileSchema, DisplaySchemaInfo, DisplayXMLInfo, and Flush on validators. EDI SDK validators use LoadSchema only; EDI SDK does not compile schemas.

Writers

The writer API shares a common base across both products: OutputData/OutputFile, FileWriteMode, StartSegment/EndSegment, Reset, and SetOutputStream.

The Design Difference

EDI Translator's writers use a method-driven approach for envelope control: StartInterchangeHeader, StartFunctionalGroupHeader, StartTransactionHeader, and their corresponding footer methods. Header field values are passed as arguments to these calls, and element data is written through WriteElementString and WriteComponentString.

EDI SDK's writers use a more readable, property-driven approach. Header fields are set on named type properties before opening each envelope level, matching the way the reader exposes envelope data. Trailers are generated automatically, and a Close call finalizes the output. For a full writing example, see Getting Started with EDIFACTWriter or Getting Started with X12Writer.

Translator-Only Writer Methods

EDI SDK-Only Writer Methods

EDI SDK: The Type System

One of the most practical improvements in EDI SDK is the typed object model for the EDI envelope hierarchy. Rather than reading interchange and message header values through generic string fields or XPath, each level of the envelope is represented by a dedicated type with named, self-documenting properties.

These types are returned by the indexed navigation properties on reader, validator, and writer components, for example, EDIFACTReader.Interchange[i] returns an EDIFACTInterchange, and EDIFACTWriter.Interchange accepts one. They cover the EDI envelope structure: interchanges, functional groups, messages, and delimiters. For typed access to the content within a message, individual segments and elements, see EDI Objects below.

EDIFACT

X12

Generic (shared across formats)

EDI SDK: EDI Objects (Code Generation)

EDI Objects are the highest-level abstraction in EDI SDK and one of its most significant advantages over IPWorks EDI Translator, which has no equivalent. EDI Objects generates a strongly-typed class for each message type directly from the schema. An ORDERS class exposes BGM, DTM, line item groups, and every element as named, typed properties, with no segment tags or index navigation needed. Repeating segments and groups become iterable collections, and correct segment ordering is enforced automatically when writing. Classes are generated by the included ediobjects.exe tool and can be regenerated from modified schemas to support custom implementations.

To learn more about EDI Objects, see Getting Started with EDI Objects for EDIFACT and Getting Started with EDI Objects for X12.

Common Migration Patterns

Reading Element Values

In IPWorks EDI Translator, element values are typically read inside a Segment event by checking XPath and reading from the current position:

reader.OnSegment += (s, e) =>
{
    if (reader.XPath == "/INVOIC/BGM/C002/1004")
        docType = reader.XText;
};

In EDI SDK, the same value can be read after parsing completes using a path string:

reader.Parse();
string docType = reader.GetElement("BGM.2.1");

Or by iterating the segment collection if the location varies or schema metadata is needed:

reader.Parse();
for (int s = 1; s <= reader.SegmentCount; s++)
{
    reader.SegmentIndex = s;
    if (reader.Segment.Tag == "BGM")
    {
        reader.ElementIndex = 2;
        reader.ComponentIndex = 1;
        docType = reader.Component.Value;
    }
}

Checking Envelope Headers

In IPWorks EDI Translator, envelope header fields are read through XPath properties inside event callbacks. In EDI SDK, the same information is available as named, typed properties directly on the event arguments:

// EDI SDK
reader.OnStartInterchange += (s, e) =>
{
    if (e.SenderIdentification != trustedPartnerId)
        throw new Exception("Unexpected sender");
};

Writing Envelope Headers

In IPWorks EDI Translator, envelope headers are opened by passing all field values as arguments:

// IPWorks EDI Translator
writer.StartInterchangeHeader("UNOB", "2", "ACME", "", "WAYNE_TECH", "", "260101", "1234", "", "1", "");

In EDI SDK, fields are set on the typed interchange object before calling the open method:

// EDI SDK
writer.Interchange.SyntaxIdentifier = "UNOB";
writer.Interchange.SenderIdentification = "ACME";
writer.Interchange.RecipientIdentification = "WAYNE_TECH";
writer.Interchange.ReferenceNumber = "1234";
writer.StartInterchange();

The field names are self-documenting and match the names used on the reader side, so the same EDIFACTInterchange type describes both incoming and outgoing interchanges.

Summary

For EDIFACT and X12 work, EDI SDK offers a cleaner API, a richer object model, and the EDI Objects layer for schema-driven code generation. The main reason to stay on IPWorks EDI Translator is TRADACOMS, HL7, VDA, or Cargo format support. EDI SDK is currently in beta, if there is a format or feature requirement not covered, contact us.