Convert is a versatile tool designed to transform XML, JSON, and COF documents into output X9.37 files. It is a general-purpose utility, to convert a wide range of input document structures. Although our goal is to accommodate most input documents, there may be structures and scenarios that are not compatible with the current parsing capabilities. If you encounter such a situation, we would be glad to work on your specific requirements by enhancing this tool.
At the center of Convert’s functionality is its ability to interpret and process input documents based on an XML descriptor that describes their structure, which we refer to as the MetaData file. This descriptor defines the element names and structures within your specific input document, and his needed to transverse and parse your specific document. Within the MetaData file, you must specify basic element names or use qualified paths to precisely target your various data element. The MetaData file must be built once, and serves as your translator definition.
Convert Invokes Write
Convert is implemented as a two-step process. It first translates your input document to an intermediate CSV file, using the item level data that has been parsed. It then directly invokes our X9Utilities -write function, which is responsible for using the items to create the x9.37 output file. Because of this, almost all -write functionality is available to the conversion process. For example, most command line switches that are used by the writer can be directly included on the command line. While Convert offers significant flexibility, some advanced features of the X9 Utilities writer, such as embedding provided addendum records within the X9.37 file, are not directly available in Convert. However, Convert still allows generation of X9.37 files with addendum records (eg, type 26 or type 28) through the HeaderXml file, which will be constant throughout the generated file.
MetaData Structure for XML and JSON Conversions
The MetaData describes the individual fields that are needed to create each logical item. These are descriptor fields are used to map our logical field name to the name or path that is used by your document to describe this data element. For example, your might map amount to amount, but you also might map amount to AMOUNT, ItemAmount, ITEM_AMOUNT, or even more complex paths such as ITEM/AMOUNT/VALUE. Path definitions are needed to when the lower level element names are not unique within your document, and thus require qualification. The field names that can be provided in your MetaData are identified in the below table.
| Item Mapping Fields (required) | Total Mapping Fields (optional but recommended) |
| <amount> <itemSequenceNumber> <micrRouting> <micrRoutingCheckDigit> <micrOnUs> <micrField4> <micrAccount> <micrProcessControl> <micrAuxOnUs> <micrEpc> <image> <frontImageName> <backImageName> <batchProfileFileName> | <debitCount> <debitAmount> <creditCount> <creditAmount> <totalCount> <totalAmount> |
In addition to these detailed item level elements, there are several high-level control fields that are needed to direct document parsing. These are as follows:
| Element Name | Usage |
| <inputFileType> | “xml” or “json”. |
| <rootElementName> | Root element name of your input document. |
| <itemsStartPath> | Sets the path where item parsing should begin. This path is very important, but can also help skip irrelevant parts of your document. |
| <itemsTriggerPath> | Specify the path that signals the start of a new item, where this path triggers the collection of item data. This assignment is crucial for correctly parsing repeating structures. |
| <totalsStartPath> | Sets the path where totals parsing should begin. This path is optional but highly recommended. Typically, totals appear at the end of the document, in a separate section or structure. Automated balancing is critical to ensure that the items within your document have been properly extracted. |
| <totalsTriggerPath> | Specify the path that identifies the first total that appears within your document. This can can any of our supported totals data elements. |
Handling Complex Fields
Some fields, like MICR fields can be provided in varying formats. For instance, the routing number might be a single 9-digit field or split into an 8-digit routing number and a separate check digit. Your metadata XML should reflect how these fields are structured in your input document. Another example is the MICR OnUs field, which might be provided as a single field (in it’s entirety) or as separate fields consisting of field4, account number, and process control.
Balancing is Recommended
If your input document includes totals, it’s highly recommended to define them in your metadata XML. This allows the Convert function to perform balancing checks, ensuring the integrity of your converted data. Balancing can be performed for separate debit and credit totals or combined file totals. If the generated output doesn’t balance against the identified totals, Convert will throw an exception, maintaining the content and spirit of the input file. As part of your testing, you will want to review output in the system log that shows how your totals were identified and extracted, to ensure that your mapping is working as expected.
Best Practices
When creating your metadata XML file, it is important to follow several best practices to ensure optimal performance and accuracy of the Convert function. You should verify that all paths specified in your XML accurately reflect the structure of your input document. This is critical, to allow Convert to navigate and extract data correctly. Additionally, make sure to include all necessary fields required for a complete X9.37 file conversion; omitting essential fields could result in incomplete or invalid output. Whenever possible, incorporate totals for balancing checks in your metadata XML. This practice allows the Convert function to perform crucial validation, ensuring the integrity of the converted data and maintaining consistency between input and output. Finally, it’s highly recommended to test your metadata XML thoroughly with a variety of sample input files. This testing process helps verify correct mapping and can reveal any potential issues or discrepancies before processing large volumes of data. By adhering to these best practices, you’ll significantly enhance the reliability and effectiveness of your conversion process, leading to more accurate and dependable X9.37 file generation.
XML Conversion Example
X9Utilities includes a folder of several conversion examples. There are several examples for each conversion type, which includes the ability to balance against embedded file totals. You will want to look closely at these examples to better understand how document translation is accomplished using the MetaData XML file.
The same MetaData XML format is shared for conversions from XML and JSON, while there is a unique format for COF. Please be aware that this is a complex and advanced topic.
| Conversion Type | MetaData XML File |
| XML or JSON | <?xml version=”1.0″ encoding=”UTF-8″?> <writerXmlFields> <attributes> <inputFileType>xml</inputFileType> <rootElementName>check-batch</rootElementName> <itemsStartPath>/check-batch/items/item</itemsStartPath> <itemsTriggerPath>/check-batch/items/item</itemsTriggerPath> <totalsStartPath>/check-batch/totals</totalsStartPath> <totalsTriggerPath>/check-batch/totals</totalsTriggerPath> <amount>amount</amount> <itemSequenceNumber>itemSequenceNumber</itemSequenceNumber> <micRouting>routing</micRouting> <micrOnUs>onUs</micrOnUs> <micrAuxOnUs>auxOnUs</micrAuxOnUs> <micrEpc>epc</micrEpc> <imageCreatorRouting>imageCreatorRouting</imageCreatorRouting> <imageCreatorDate>imageCreatorDate</imageCreatorDate> <frontImage>frontImageFileName</frontImage> <backImage>backImageFileName</backImage> <batchProfileFileName>batchProfile</batchProfileFileName> <debitCount>debitCount</debitCount> <debitAmount>debitAmount</debitAmount> <creditCount>creditCount</creditCount> <creditAmount>creditAmount</creditAmount> <totalCount>totalCount</totalCount> <totalAmount>totalAmount</totalAmount> </attributes> </writerXmlFields> |
| COF | <?xml version=”1.0″ encoding=”UTF-8″?> <writerCofFields> <attributes> <inputFileType>cof</inputFileType> <trimLeadingZerosOnAccountNumber>true</trimLeadingZerosOnAccountNumber> <trimLeadingZerosOnAuxOnUs>true</trimLeadingZerosOnAuxOnUs> <trimLeadingZerosOnCheckNumber>true</trimLeadingZerosOnCheckNumber> <trimLeadingZerosOnProcessControl>true</trimLeadingZerosOnProcessControl> <trimLeadingZerosOnEpc>true</trimLeadingZerosOnEpc> <padZeroesToLengthOnAccountNumber>0</padZeroesToLengthOnAccountNumber> <padZeroesToLengthOnAuxOnUs>0</padZeroesToLengthOnAuxOnUs> <padZeroesToLengthOnCheckNumber>0</padZeroesToLengthOnCheckNumber> <padZeroesToLengthOnProcessControl>0</padZeroesToLengthOnProcessControl> <padZeroesToLengthOnEpc>0</padZeroesToLengthOnEpc> </attributes> </writerCofFields> |
Convert accepts all command line options that are made available by Write. They will be needed during the creation of your output x9.37 file.