CompAnalytics.X9 0.1.1

CompAnalytics.X9

This library contains classes that represent, read, and write binary X9.100-187 image cash letter files used for electronic transmission of checks to/from a bank. It includes tools for reading the files from disk into an X9Document representation that mimics the structure of the file's various records and fields in friendly, interoperable types. X9Documents can also be created from scratch, then written out to the binary X9 format, enabling simple X9 file creation for your .NET environment use case. All types also offer robust type coercion, bounds-checking for each fixed-length field, comparison utilities to ensure equality across files, and informative exception messages when attempting to violate the X9.100-187 specification. The library is being used in production for transmission of millions of dollars by Composable Analytics.

Authors

1. Ryan O'Shea https://ryanoshea.com for Composable Analytics, from Oct. to Dec. 2019.

API Specification

Full public API specifications can be found here.

Source

Full source is available on GitHub. You may encounter problems trying to build as the csproj found the repository is the one we use internally at Composable, so you'll need to manually resolve DLL dependencies for CompAnalytics.* libraries.

Supported Record Types

The following X9 file record types are fully supported for reading and writing.

* See Limitations

Examples

Reading an X9 File

The following example reads an X9 file from disk and extracts the embedded check images to TIFFs on disk.

string path = @"C:\Temp\sample.x9";
string imageOutDir = @"C:\Temp\SampleCheckImages";
using (Stream x9File = File.OpenRead(path))
using (X9Reader reader = new X9Reader(x9File))
{
    doc = reader.ReadX9Document();
    reader.WriteImagesToDisk(imageOutDir);
}

Authoring an X9Document

Nuget places limits on Readme size. You can see this example at this gist.

Writing an X9 File

This example uses an X9Writer to write the contents of an X9Document to a binary X9 file on disk.

X9Document doc = ...; // create this using example above
string outFilePath = @"C:\Temp\example.x9";
using (X9Writer writer = new X9Writer(doc))
using (MemoryStream byteStream = new MemoryStream(writer.WriteX9Document()))
using (FileStream x9FileStream = File.Create(outFilePath))
{
    byteStream.CopyTo(x9FileStream);
}

Limitations

This library was originally developed in 2019 during an accounts-receivable automation project undertaken by Composable Analytics, Inc., where the destination institution was JPMorgan Chase. As a result, the library has the following limitations:

1. Only the X9.100-187 file standard is supported. Specifically, the library was modeled after JPMorgan's Merchant ICL Deposit specifications v4, R7.
2. Some classes, notably the various classes modeling each type of record in the X9 file (X9Records), contain a method for quickly setting the values of some fields based on a limited set of arguments and populating other fields with JPMorgan's defaults. There are also DataContract classes under CompAnalytics.X9.JPMorganAuthoring that specifically model only the non-static fields needed when sending these files to JPMorgan. While these have been left in for compatibility with our original use case, these specialized classes & methods can be safely ignored and the library can be used for general-purpose X9 file creation.
3. To reduce complexity, the library only supports one dynamic-length field per record. As a result, the Image View Data Record (Records.ImageViewDatRecord) supports arbitrary-length image data (Field 19), but the other dynamic-length fields in that record are not supported and must be left empty to produce a valid file. This includes Field 17, the digital signature, and Field 15, the image reference key. The corresponding length fields for these two fields (14 and 16, respectively), must also be left at their default value, 0, indicating that the fields both have a length of zero bytes.
4. Images are provided to the ImageViewDataRecord by supplying a byte[] representing the image file. These must be from TIFF images compressed with CCITT Group 4. Check your institution for image dimension and resolution requirements.
5. Currently, the library does not support reading ICLr return files for returned checks. There are plans to support these in the future.

Additionally, the library takes a dependency on Entity Framework due to its reliance on CompAnalytics.Contracts, our base assembly for all DataContracts sent over the wire in the Composable data analytics platform, of which this library is a component. We would like to remove this dependency, but we currently aren't able to. None of the Entity Framework types referenced by CompAnalytics.Contracts are used by CompAnalytics.X9, so as long as you can include the EF dependency and resolve any type load issues, you won't need to worry about runtime errors caused by version mismatches.