1. Install the Parser Package

Start with the parser project itself and only add extra modules when your application really needs them. The parser is the foundation for envelope handling, transaction-set traversal, validation, and ACK generation.

dotnet add package HIPAAsuite.AuroraParser

Do not expand the scope until the parser workflow is working end to end.

2. Initialize Schemas and Code Sets

Load only the APF schemas and CSV code sets your application actually uses. Doing this once at startup keeps per-request parsing lean and makes behavior more predictable across environments.

using HIPAAsuite.AuroraParser;
using HIPAAsuite.AuroraParser.CodeSets;

APFFactory.Initialize(APFFileEnum.Claim_5010x222A1);
APFFactory.Initialize(APFFileEnum.Payment_5010x221A1);

CsvLoader.Instance.StartLoading(new Dictionary<string, CsvLoader.CsvLoadRequest>
{
    { CsvFileEnum.States.ToString(), new CsvLoader.CsvLoadRequest(1, hasHeader: false) },
    { CsvFileEnum.ZipCodes.ToString(), new CsvLoader.CsvLoadRequest(2, hasHeader: false) }
});

await CsvLoader.Instance.WaitUntilLoadedAsync();

3. Parse a File or String

The standard pattern is to pair LazyParserLite with CommonEDIHandler. The parser streams segments; the handler builds the interchange, functional group, and transaction-set objects.

using AuroraParser;
using HIPAAsuite.Data;

using var handler = new CommonEDIHandler();
using var parser = new LazyParserLite(handler);

var ok = parser.Parse("sample-837.edi");
if (!ok)
{
    Console.WriteLine("Parse failed.");
    return;
}

Console.WriteLine($"Interchanges: {handler.Interchanges.Count}");

For uploads or queue messages, parse from a string payload instead of a file path.

4. Inspect the Object Graph

The main object model is Interchange -> FunctionalGroup -> TransactionSet. In most applications, that is where your business logic begins.

foreach (var interchange in handler.Interchanges)
{
    Console.WriteLine($"ISA Control Number: {interchange.ISA?.InterchangeControlNumber}");

    foreach (var group in interchange.FunctionalGroups)
    {
        Console.WriteLine($"Group Type: {group.GS?.FunctionalIdentifierCode}");

        foreach (var transactionSet in group.TransactionSets)
        {
            Console.WriteLine($"Transaction Set: {transactionSet.ST?.TransactionSetId}");
            Console.WriteLine($"Segments: {transactionSet.Segments.Count}");
        }
    }
}

5. Validate After Parsing

Validation should happen immediately after parsing, while the interchange is still close to the raw input. That keeps error reporting tied to the original control numbers and segment positions.

foreach (var interchange in handler.Interchanges)
{
    var validator = Validator.GetValidator(interchange);
    validator.ValidateInterchange();

    if (validator.Errors.Any())
    {
        foreach (var error in validator.Errors)
        {
            Console.WriteLine($"{error.LineNumber}: {error.Message}");
        }
    }
}

Treat validation as part of the parser workflow, not as a separate product concern.

6. Generate ACKs

Acknowledgement generation belongs close to validation because it reflects the result of syntactic and structural checks on the parsed interchange.

var ack999 = handler.Generate999();
var ackText = ack999.ToEdiString();

File.WriteAllText("ack-999.edi", ackText);

If your pipeline also transmits ACKs over FTP or API, keep that delivery logic outside the parser layer.

7. Transform Parsed Output

Serialization is usually the first step after a successful parse. Keep it separate from parse and validation logic so the parser remains the system of record for X12 structure.

using HIPAAsuite.AuroraObjectsTransformers;
using Newtonsoft.Json;

var json = JsonConvert.SerializeObject(
    handler.Interchanges,
    new InterchangeListJsonConverter(includeMetadata: true, namingConvention: NamingConvention.CamelCase)
);

Console.WriteLine(json);

8. Split or Batch Transaction Sets

The parser library already includes helper support for splitting or regrouping parsed interchanges. This is still parser-adjacent work because it operates on the parsed object graph and envelope metadata.

using HIPAAsuite.AuroraParser.Helpers;

var interchange = handler.Interchanges.First();

FileSplitter.ProcessAndValidateInterchangesToDirectories(
    new List<Interchange> { interchange },
    Path.Combine(outputRoot, "Compliant"),
    Path.Combine(outputRoot, "NonCompliant"),
    "sample-837.edi",
    updateICN: true,
    updateFGCN: true,
    updateTSCN: true
);

9. Performance and Troubleshooting

The most common real issues are not exotic. They are missing schema initialization, invalid ISA-derived delimiters, envelope mismatches, or licensing configuration problems.

• Initialize APF files before the first parse.
• Do not hardcode delimiters; let the parser infer them from ISA.
• Keep parse, validate, and ACK generation in one coherent flow.
• Log control numbers and transaction-set IDs early so failures are traceable.

handler.ExceptionOccurredEvent += ex => Console.WriteLine(ex.Message);
handler.ReportProgressEvent += progress => Console.WriteLine(progress.ToString("P0"));

10. Parser Integration Checklist

Before expanding the integration, make sure the parser path itself is complete and repeatable.

• Schema initialization runs before the first parse.
• The parsed interchange graph is inspected directly during development.
• Validation runs on the same parsed interchange instance that produced the ACK.
• Output shaping or split helpers are added only after the base parse flow is stable.