X9Utilities Overview — x9utilities is a command line (batch) utility environment which supports a variety of functions to facilitate commonly required x9 file processing. The following specific functions are currently implemented within X9Utilities provides an extremely high level functionality for x9 users who need to read and write x9 files from their internal applications, but do not require the more extensive integration and development complexities that are typically associated with implementing an SDK based application. Why acquire and use more complex and expensive tools than you really need? If you need to read and write x9 files, then X9Utilities is the best tool for the job at hand. Since X9Utilities is implemented as a command line EXE, it can be invoked from Java, C++, and .Net environments.
- X9Utilities will do all of the heavy lifting on your behalf. It uses our SDK and assumes all responsibility for field alignment and padding based on each x9 field definition, per the x9 standards. Images are converted as needed from various formats to be TIFF x9.100-181 compliant.
- X9Utilities is designed to process both ICL and ICLR files. It supports a wide variety of x9 record types including credits, addendums and type 68 user records. Our file writer can ensure that a unique File ID Modifier is assigned to each output file per calendar date.
- X9Utilities is full function, easy to use, includes our standard support, leverages our SDK, and is very competitively priced when compared to other alternatives within the x9 marketplace.
- X9Utilities is targeted for those organizations who need access to the data (x9 records and tiff images) that are embedded within x9 files. X9Utlities provides the power you need to both read and write X9 files using your languages such as VB, C++, Java, PERL, RUBY, Python, or similar tools. Anything that can read and write CSV files can work with X9Utilities.
| Product | Supported Functions | Supported Environments |
|---|---|---|
| X9Utilities | Read, Write, Import, Export, Validate, Merge, Scrub, Update, Split, Compare, ImagePull, FindReplace. | Since X9Utilities is Java based, it can be run on any platform which supports the Java JVM. X9Ware typically provides X9Utilities as a compiled executable (for the Windows environment) but may also be provided as a Java JAR when needed for Linux cloud-container based installations. |
| X9Export | Export | Contains only the x9utilities export function and is available for Windows only. |
| X9Merge | Merge | Contains only the x9utilities merge function and is available for Windows only. |
Command Line Functions
| Function | Usage |
|---|---|
| read | Reads an x9 file in virtually any industry defined x9 format and parses the file into the corresponding data and image components. The x9 data is written to a single CSV file which can be browsed or otherwise processed by your applications. Each x9 record will be written as a single row and each x9 field is written as a separate CSV field. |
| write | Write is an advanced tool that can be used to easily create new x9 output files. In order to simplify the overall x9 file creation process, Write controls the creation of bundles and their associated trailer records. It calculates and inserts all required totals within the bundle, cash letter, and file control trailer records. All of this is done automatically behind the scene. Writer input is created by your internal applications in a simple CSV format. Images must be provided in TIFF image exchange (x9.100-181) format as typically created by all industry scanners. A parameter file allows you to specify various options including header and cash letter header values which are provided externally in an XML file. Through the use of these header file parameters, write is designed with the goal of being able to create an x9 file for any financial institution. We have incorporated a large number of options which already make this possible for many endpoints and we continue to enhance this process to work towards that goal. This may not always be possible given the complexities that have been implemented by some processors. Please let us know where we can make enhancements which may involve consulting costs subject to level of difficulty and uniqueness of the required solution. |
| export | Reads an x9 file and creates an output CSV file which maps directly to every x9 record and field. Images can be optionally written to an output folder. Export provides direct access to your x9 data and images so you can process them in your own applications. |
| import | Reads the csv format that is created by export to write an x9 output file. Images tags are embedded within the csv file to uniquely identify each front and back image (in TIFF format), where the image file name is populated directly into field 52.19 as proxy for the image itself. The importer will retrieve and embed those images within the constructed x9 file. |
| validate | Reads an x9 file in industry defined formats and applies x9 data and image validations against the parsed records. The command line identifies all inputs and outputs as well as the x9 specification to be applied. Identified validation errors are written to an output CSV file. |
| merge | Combines one or more x9 input files into x9 output file(s). Merge is a robust process which can be run against a potentially large number of input x9 files. Eligible input files are selected from an input “landing zone” which is identified on the command line. Merge is designed to be run periodically against the landing zone, most probably as a scheduled task, where all current content of the input folder will be merged into one or more output x9 files. |
| scrub | Reads an x9 file in industry defined formats and applies user defined actions to remove proprietary and confidential information from the input file creating a new output x9 file. In addition to the x9 data fields, scrub can optionally apply replacement actions against the images associated with each item. The actions to be performed can be saved in a user defined scrub configuration file which is available for future reuse. Scrub has a standard list of available cleansing actions that can be selected based on your specific requirements. |
| update | Update reads an existing x9 file in common industry defined formats and performs replacement operations against one or more fields within the file. This process consists of searching for user defined values within specific record types and fields and then replacing those values (when found) with new data values in a newly created x9 file. |
| split | Split reads an existing x9 file in common industry defined formats and splits (divides) into output segments, where each output is a separate x9 file. The file, cash letter, and bundle headers are copied from the input x9 to the output x9. We will refer to each output x9 file as a logical segment. |
| compare | Compares two x9 files that are expected to be equal. Items must appear within the file in the same logical order. Any encountered differences at the record, field, or image level will be identified and reported via an output csv file. Specific fields can be excluded from the comparison when they are expected to be different. |
| imagePull | Reads an input CSV which represents items to be pulled from one or more x9 files with results written to an output CSV image folders. Input is reorganized so each associated x9 file is only read once. Output consists of detailed information about each located item and the name of the front/back image files which have been written. |
| findReplace | Reads an x9 file and will search for specific values in specific fields and replace them with new values. Search and replace values are provided in an external XML file. A CSV file is created which lists the records, fields, and values that have been replaced. |
Read and Write
Reading and writing x9 files can become a complex process, especially given the various record types, data fields, and formatting requirements. This is further complicated by the variable length records that are stored within the file layout and the common practice of using the EBCDIC character set (not ASCII) when creating these files.
The Read and Write utilities are designed with the purpose to make this process as easy as possible. By using these tools, you can concentrate on the actual x9 data and not the underlying complexities associated with x9 files.
Read and Write share a common CSV data format. This means that you can create a CSV file using Read and then pass that CSV file to Write to create a corresponding x9 output file which will contain those same items.
The CSV file begins with a header line and is terminated with an “end” line. The structure of the CSV file is as follows:
header definition (which can be “header”, “headerCsv”, or “headerXml”)
zero or more items
“end”
Note that a file with zero items is considered valid and will result in the creation of a file with record types 01, 10, 90, and 99.
A sample CSV file is as follows:
“header”,”x9.37″,20140808,20140810,1201,03,123456780,”VIEW”,123456780,”VIEW”,”A”,”T”,”N”,,,,123456780,123456780,1,”X9ASSIST”,,,”I”,”G”,01,”C”,,300,,,,
25,,,08777070,6,”29602722/5526″,0000010002,44000001,”G”,8,1,”Y”,01,0,”B”
“image”,”c:/users/x9ware2/documents/x9_assist/files_Utilities/Test file with 2 checks reader_IMAGES/Bundle_000003/Image_000007_amount_10002_front.tif”,087770706,20140807
“image”,”c:/users/x9ware2/documents/x9_assist/files_Utilities/Test file with 2 checks reader_IMAGES/Bundle_000003/Image_000009_amount_10002_back.tif”,087770706,20140807
25,,,09777059,2,”60666044/5587″,0000010004,44000002,”G”,8,1,”Y”,01,0,”B”
“image”,”c:/users/x9ware2/documents/x9_assist/files_Utilities/Test file with 2 checks reader_IMAGES/Bundle_000003/Image_000013_amount_10004_front.tif”,097770592,20140807
“image”,”c:/users/x9ware2/documents/x9_assist/files_Utilities/Test file with 2 checks reader_IMAGES/Bundle_000003/Image_000015_amount_10004_back.tif”,097770592,20140807
“end”
Export and Import
The CSV file format that is implemented by our Read and Write is X9HeaderXml is proprietary and unique to X9Ware LLC. You can instead use our Export and Import tools against your x9 files. Export and Import are complimentary tools. Export will read an x9 file and create a CSV file with records formatted exactly as they appear within the x9 file. Importer takes a similarly formatted CSV file and creates an output x9 file. Both of these tools allow you to specify the x9 configuration via the command line. This is an important consideration, since the fields within an x9 record may potentially vary based on the x9 specification that is being used.
A sample CSV file is as follows:
01,03,”T”,123456780,123456780,20140810,1201,”N”,”VIEW”,”VIEW”,”A”,,,
10,01,123456780,123456780,20140808,20140810,1201,”I”,”G”,1,”X9Assist”,,”C”,,
20,01,123456780,123456780,20140808,20140810,57000000,1,,123456780,,
25,,,08777070,6,”29602722/5526″,0000010002,44000001,”G”,8,1,”Y”,01,0,”B”
26,1,123456780,20140807,44000001,,,,”Y”,0,,,
50,1,087770706,20140807,00,00,0006302,0,00,0,,,,,0,,
52,123456780,20140808,,44000001,,,,0,,,,,0000,,0,,0006302,”c:/users/x9ware2/documents/x9ware/files_Utilities/Test file with 2 checks exporter_IMAGES/Bundle_000003/Image_000007_amount_10002_front.tif”
50,1,087770706,20140807,00,00,0001865,1,00,0,,,,,0,,
52,123456780,20140808,,44000001,,,,0,,,,,0000,,0,,0001865,”c:/users/x9ware2/documents/x9ware/files_Utilities/Test file with 2 checks exporter_IMAGES/Bundle_000003/Image_000009_amount_10002_back.tif”
25,,,09777059,2,”60666044/5587″,0000010004,44000002,”G”,8,1,”Y”,01,0,”B”
26,1,123456780,20140807,44000002,,,,”Y”,0,,,
50,1,097770592,20140807,00,00,0006679,0,00,0,,,,,0,,
52,123456780,20140808,,44000002,,,,0,,,,,0000,,0,,0006679,”c:/users/x9ware2/documents/x9ware/files_Utilities/Test file with 2 checks exporter_IMAGES/Bundle_000003/Image_000013_amount_10004_front.tif”
50,1,097770592,20140807,00,00,0001865,1,00,0,,,,,0,,
52,123456780,20140808,,44000002,,,,0,,,,,0000,,0,,0001865,”c:/users/x9ware2/documents/x9ware/files_Utilities/Test file with 2 checks exporter_IMAGES/Bundle_000003/Image_000015_amount_10004_back.tif”
70,0002,000000020006,000000020006,00004,,
90,000001,00000002,00000000020006,000000004,”File Generator”,20140810,
99,000001,00000018,00000002,0000000000020006,,,
Validate
Command line switches (parameters) are used to further control Validate operation. By default, the x9.37 rules will be applied to the x9 file during validation. However, you can also use a command line switch to apply an alternate x9 configuration for the validation process.
Scrub
Scrub uses an xml parameter file to define the actions to be applied to the input x9 file. This xml file is created and testing using our X9Assist product where you can define and review these parameters and repetitively test them against x9 files to ensure that they are providing desired results. These xml definitions are stored by X9Assist in folder / Documents / x9_assist / xml / scrub /. X9Assist allows you to create as many of these definitions as you need to perform your desired scrub actions. The shared used of these xml parameter files between X9Assist and X9Utilities is a key part of our design of these tools.
More Information
We have included files below as a high level example of the files that are associated with Reader and Writer, and simple batch files which could be used to invoke them. Both of these functions will write summary totals to an output file which you can use to confirm successful completion. The -x switch is used to write totals to an output XML file while the -t switch is used to write totals to an output text file.
- “Test ICL with 10 checks.csv” is an example of the items file that is input to Writer and is created by Reader. This example uses an instream header file (which is row one within the CSV) with each image having a fully qualified file name.
- “Test ICL with 10 checks2.csv” is a Writer input file example which can be easier to use when creating output x9 files. This example uses “headerXml” (on row one) which allows file header information to be stored and maintained in an external XML fie. It also uses an “imageFolder” definition (on row two) which allows all images to have relative file names.
- “Test ICL with 10 checks3.csv” is a Writer input file example which creates items using the MICR line that is captured by your scanner. This example uses “headerXml” (on row one) which allows includes the definitions of your MICR line symbols. It also uses an “imageFolder” definition (on row two) which allows all images to have relative file names.
- “Test ICL with 10 checks_Images.zip” can be unzipped to create an image folder. This is an example of the images that are input to the Writer and as created by the Reader.
- fileWriterSummaryTotals.txt is an example of the totals created by Writer using the -t command line option.
- fileWriterSummaryTotals.xml is an example of the totals created by Writer using the -x command line option.
- x9filereader.bat is an example of a simplistic batch file that can be used to invoke Reader.
- x9filewriter.bat is an example of a simplistic batch file that can be used to invoke Writer.
Please contact us for technical documentation for the use of our X9Utilities product.