Getting Started with X12Writer

Requirements:
EDISDK

Introduction

The X12Writer component provides a straightforward way to generate X12 transaction sets programmatically. Designed to be intuitive and flexible, it simplfies common tasks, like building envelope headers and creating transaction sets.

This guide walks through the basics of creating a simple X12 document, as well as how to handle validation.

Tip: Download the latest version of EDISDK to follow along.

Step 1: Set Up

The X12Writer component is highly flexible, and its configuration largely depends on intended use. The default settings are sufficient for many cases, the component will write to an in-memory string and use standard delimiters and encoding. However, if a change in behavior is desired, certain settings must be applied before starting to write to ensure consistency throughout the document.

Key settings to configure before writing include:

• Output mode options (OutputFile, OutputData, or SetOutputStream)
• File write mode options (overwrite vs. append)
• Encoding options (e.g., iso-8859-1)
• Segment delimiters and suffixes

Setting these before writing begins ensures that all segments and transaction sets use the same conventions consistently.

Step 2: Handling Headers

Headers in the X12Writer component are human-readable and intuitive. Each level of an X12 document has its own set of header fields. Refer to the type definitions in the help documentation for a complete list of fields. The example below demonstrates the correct order in which headers should be opened:

Interchange -> Functional Group -> Transaction Sets.

// Interchange headers
writer.Interchange.SenderID = "SENDERISA      ";
writer.Interchange.ReceiverID = "RECEIVERISA    ";
writer.InterchangeControlVersionNum = "00401";
writer.Interchange.InterchangeControlNum = "000000020";
writer.Interchange.AckRequest = "0";
writer.StartInterchange();

// Functional Group headers 
writer.FunctionalGroup.FunctionalIdentifierCode = "IN";
writer.FunctionalGroup.AppSenderCode = "SENDERDEPT";
writer.FunctionalGroup.AppReceiverCode = "007326879";
writer.FunctionalGroup.Version = "004010";
writer.StartFunctionalGroup();

// Transaction Set headers
writer.TransactionSet.TransactionSetIDCode = "810";
writer.TransactionSet.TransactionSetControlNum = "000000001";
writer.StartTransactionSet();

Note: Header fields are applied the next time the corresponding start method is called. To ensure a header is generated with the desired values, set its fields before calling StartInterchange, StartFunctionalGroup, or StartStartTransactionSet. Fields set afterward will be applied the next time a header of that type is generated.

Step 3: Writing Segments

After a transaction set header has been started, segments form the body of the transaction set. The component does not enforce schema rules directly, leaving that responsibility to the application. This design provides the flexibility to target any schema version or custom variation, while still ensuring that valid X12 output is produced when schema rules are followed.

The process is straightforward: begin a segment with StartSegment, write elements or composites, and then close the segment with EndSegment. Composite elements follow the same pattern, open with StartCompositeElement, write the components, and close with EndCompositeElement. If an element or component needs to be skipped, simply write an empty value in its place.

 writer.StartSegment("SLN");
 writer.WriteElement("1");
 writer.WriteElement("");
 writer.WriteElement("O");
 writer.WriteElement("");
 writer.StartCompositeElement();
 writer.WriteComponent("52");
 writer.WriteComponent("00");
 writer.EndCompositeElement();
 writer.WriteElement("5.00");
 writer.WriteElement("PY");
 writer.EndSegment();

Step 4: Creating Footers

After setting up headers and writing transaction set segments, call EndTransactionSet to close the transaction set. Similarly, use EndFunctionalGroup and EndInterchange to close the associated section. X12Writer handles all trailers automatically, so it is easy to include multiple transaction sets, functional groups, or interchanges within a single transmission. Once the transmission is complete, call Close to ensure all resources are released.

Step 5: Validating Writer Output (Optional)

If required, the application can validate the output using X12Validator component. Set the X12Validator's InputFile to the X12Writers’s output and handle events for schema resolution and validation warnings. An example on how that might be accomplished is included below:

X12Validator validator = new X12Validator();
validator.InputFile = X12writer.OutputFile;

validator.OnResolveSchema += (s, e) =>
{
    validator.LoadSchema(SchemaPath, e.TransactionSetIDCode);
};

// Handle validation warnings in real time or review them using the ValidationErrors collection. 
validator.OnValidateWarning += (s, e) =>
{
    Console.WriteLine($"Validation Error: [{e.Position}-{e.Line},{e.Column}] {e.ErrorCode}: {e.ErrorMessage}");
};

// Run validation
validator.Validate();

The validation will check for missing or out-of-order segments, invalid data formats, and incorrect code list values. Handling warnings and errors through events allows immediate response to issues.

Tip: Run validation before sending a transmission to catch errors early and ensure transaction sets comply with the standard.

Conclusion

The X12Writer and X12Validator components provide a clear and reliable way to generate and verify X12 documents. With human-readable headers, flexible segment management, and schema-based validation, they enable applications to produce structured business data that meets required standards efficiently.

Whether creating a single transaction set, multiple transaction sets within functional groups, or full transmissions across multiple interchanges, X12Writer simplifies building and finalizing X12 documents. Using X12Validator ensures that transaction sets conform to schemas, catching missing segments, invalid codes, or incorrect formats before transmission.

By following the steps in this guide, developers can quickly get up and running, automating X12 transaction set creation and compliance.