ACHConverter Class

Properties   Methods   Events   Config Settings   Errors  

The ACHConverter class is used to convert ACH files into XML, for the purpose of easy viewing and editing. The class can also convert this XML back into the ACH format, so it may later be processed by the ACH network. Validation of these files occurs during the translation process.

Syntax

inpay.Achconverter

Remarks

This class is used for translating ACH files back and forth between the complex data format used by the ACH network and simple XML. By representing an ACH file as an XML structure, the viewing, parsing, and editing of individual ACH records can be easily accomplished. An XML document can be built from scratch and then use the ACHConverter class to convert it to ACH format.

The ConvertACH and ConvertXML methods are used to go back and forth between the ACH format and XML formats. ConvertACH converts from ACH to XML, and ConvertXML converts from XML back into ACH format. The data to be converted is specified by SetInputStream, InputFile or InputString, and the results are written to SetOutputStream, OutputFile or OutputString.

When the parsing is taking place, the source file is checked for validity in several different ways. The format and sequence of the records in the file is checked, as well as the data in each field in a record. Any formatting error or incorrect data (for instance, a character in an numeric-only field) will cause the validity checks to fail. In addition, the totals in each Batch Control Record and in the final File Control Record are checked against values computed as the class parses each record (this last check may be overridden by the VerifyMode property).

For example: ACHConverter1.InputFile = "c:\achtestfile.txt" ACHConverter1.OutputFile = "c:\xmltestfile.xml" ACHConverter1.VerifyMode = vmValidateTotals ACHConverter1.ConvertACH()

After the above code completes successfully, "c:\xmltestfile.xml" will contain the XML representation of the input ACH file. In addition, the following properties will be filled with information about the ACH file that was just parsed:

• FileBatchCount
• FileBlockCount
• FileCreditTotal
• FileDebitTotal
• FileEntryCount
• FileEntryHash

Note: The XML document created (and parsed) by this class is defined in the Schema property.

Property List

---

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

FileBatchCount	Total number of batches contained in the file.
FileBlockCount	Total number of blocks in a file.
FileCreditTotal	Total amount credited to the merchant's bank account.
FileDebitTotal	Total amount debited from the merchant's bank account.
FileEntryCount	Total number of entries in a file.
FileEntryHash	Hash of the routing numbers from each detail record in the file.
InputFile	Specifies the file to read data from when calling ConvertXML or ConvertACH .
InputString	Data in memory to read from when calling ConvertXML or ConvertACH .
OutputFile	Specifies the file data is written to when calling ConvertXML or ConvertACH .
OutputString	Contains the results from ConvertXML or ConvertACH .
Schema	Returns the XSD Schema used to create XML from ACH files.
VerifyMode	Determines how the totals in the Batch and File control records are validated.

Method List

---

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Config	Sets or retrieves a configuration setting.
ConvertACH	Converts a file from ACH format into XML.
ConvertXML	Converts an XML file into ACH format.
Reset	Reset the internal state of the class and all properties to their default values.
SetInputStream	The input stream to read from when calling ConvertXML or ConvertACH .
SetOutputStream	The output stream to write to when calling ConvertXML or ConvertACH .

Event List

---

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Error	Information about errors during data delivery.

Config Settings

---

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

CloseStreamAfterConversion	If true, the class will close the output stream after conversion.
BuildInfo	Information about the product's build.
GUIAvailable	Tells the class whether or not a message loop is available for processing events.
LicenseInfo	Information about the current license.
MaskSensitive	Whether sensitive data is masked in log messages.
UseDaemonThreads	Whether threads created by the class are daemon threads.
UseInternalSecurityAPI	Tells the class whether or not to use the system security libraries or an internal implementation.

FileBatchCount Property (ACHConverter Class)

Total number of batches contained in the file.

Syntax

public long getFileBatchCount();

Default Value

0

Remarks

A file may contain a minimum of 1 and a maximum of 999999 batches.

This property is read-only.

FileBlockCount Property (ACHConverter Class)

Total number of blocks in a file.

Syntax

public long getFileBlockCount();

Default Value

0

Remarks

Each block consists of 10 records, or approximately 960 characters.

This property is read-only.

FileCreditTotal Property (ACHConverter Class)

Total amount credited to the merchant's bank account.

Syntax

public String getFileCreditTotal();

Default Value

"0"

Remarks

This property contains the total amount of all transactions that credit funds to the merchant's account (this is a gross amount).

This property is read-only.

FileDebitTotal Property (ACHConverter Class)

Total amount debited from the merchant's bank account.

Syntax

public String getFileDebitTotal();

Default Value

"0"

Remarks

This property contains the total amount of all transactions that debit funds from the merchant's account (this is a gross amount).

This property is read-only.

FileEntryCount Property (ACHConverter Class)

Total number of entries in a file.

Syntax

public int getFileEntryCount();

Default Value

0

Remarks

An entry is defined as a Detail Record or an Addenda Record. Header and Control records are ignored.

This property is read-only.

FileEntryHash Property (ACHConverter Class)

Hash of the routing numbers from each detail record in the file.

Syntax

public String getFileEntryHash();

Default Value

"0"

Remarks

This property contains a 10-character long hash of all of the recipient routing numbers in the file. This is used as a check to ensure that no records were lost in the transmission of this ACH file.

This property is read-only.

InputFile Property (ACHConverter Class)

Specifies the file to read data from when calling ConvertXML or ConvertACH .

Syntax

public String getInputFile();


public void setInputFile(String inputFile);

Default Value

""

Remarks

This property contains the path and filename to the ACH or XML file you wish to parse and convert.

InputString Property (ACHConverter Class)

Data in memory to read from when calling ConvertXML or ConvertACH .

Syntax

public String getInputString();


public void setInputString(String inputString);

Default Value

""

Remarks

This property contains the ACH or XML data, in memory, that you wish to parse and convert.

OutputFile Property (ACHConverter Class)

Specifies the file data is written to when calling ConvertXML or ConvertACH .

Syntax

public String getOutputFile();


public void setOutputFile(String outputFile);

Default Value

""

Remarks

This property contains the path and filename where you wish to store your converted results.

OutputString Property (ACHConverter Class)

Contains the results from ConvertXML or ConvertACH .

Syntax

public String getOutputString();

Default Value

""

Remarks

If SetOutputStream and OutputFile have not been set, the results of the ConvertXML or ConvertACH methods will be stored in memory and returned by the OutputString property.

This property is read-only.

Schema Property (ACHConverter Class)

Returns the XSD Schema used to create XML from ACH files.

Syntax

public String getSchema();

Default Value

""

Remarks

This property returns the schema (XSD format) that the class uses to generate XML from an ACH file. This same schema is used when parsing XML to re-create an ACH file. During the parsing process, if the input XML does not conform to the schema the translation process will fail with an error.

This property is read-only and not available at design time.

VerifyMode Property (ACHConverter Class)

Determines how the totals in the Batch and File control records are validated.

Syntax

public int getVerifyMode();


public void setVerifyMode(int verifyMode);


Enumerated values:
  public final static int vmValidateTotals = 0;
  public final static int vmComputeTotals = 1;
  public final static int vmNoValidation = 2;

Default Value

0

Remarks

Batch Control Records contain several fields that provide information about each batch included in the ACH file. These include an Entry Count (number of records in the batch), Credit Total (total funds added to the merchant's account), Debit Total (total of funds removed from the merchant's account), and a hash used to verify that there are no missing transactions. The ending File Control record contains similar information about the entire batch The final record in an ACH file is the File Control Record. This record contains several fields that provide information about all of the batches and all of the transactions in the ACH file. These fields are exposed in the following properties:

FileBatchCount	Total number of batches contained in this ACH File.
FileBlockCount	Total number of blocks (each block consists of 960 characters).
FileCreditTotal	Gross amount of funds deposited into the merchant's account.
FileDebitTotal	Gross amount of funds removed from the merchant's account
FileEntryCount	Total number of entries in the file (sum of all entries in each batch)
FileEntryHash	Used to validate that there are no transactions missing from the file

There are similar fields for each of the batches contained within the ACH file, but only the final totals are exposed. The class carefully computes these values as the input is parsed, and the table below shows how they are validated:

Verify Mode	Description
vmValidateTotals (0)	The totals listed in each control record in the file are compared against the totals that the class computes itself. If there is any mismatch, the class fails with an error.
vmComputeTotals (1)	The totals listed in each control record in the file are ignored. The values computed by the class are substituted. This is useful when adding or removing records from the ACH or XML files.
vmNoValidation (2)	No validation is performed. The values in the file are used, and the computed values are ignored.

Config Method (Achconverter Class)

Sets or retrieves a configuration setting.

Syntax

public String config(String configurationString);

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

ConvertACH Method (Achconverter Class)

Converts a file from ACH format into XML.

Syntax

public void convertACH();

Remarks

This method converts an ACH-formatted file into an XML format. This XML can easily be viewed, edited, or otherwise manipulated, and then converted back to ACH format at a later date using the ConvertXML method. The source ACH file can be specified by the SetInputStream method or the InputFile and InputString properties, and the destination XML by the SetOutputStream method or OutputFile, and OutputString properties.

When the ConvertACH method is called, the source ACH file is validated in several ways. The format of each record in the file is checked before it is converted to XML. The validity of data contained within each field in the record is also checked. Any formatting error or incorrect data (for instance, a character in an integer-only field) will cause the class to fail with an error.

In addition, each ACH file contains several Batch Control records and a final File Control Record. These records contain information about the transactions contained within the ACH file. The data contained within these control records is used to make sure the ACH files have not been corrupted, and have not lost records in the transmission process. The class will by default validate the data contained in these control records. However, you can override this functionality by changing the VerifyMode (note that VerifyMode does not affect the format or data validity checks).

ConvertXML Method (Achconverter Class)

Converts an XML file into ACH format.

Syntax

public void convertXML();

Remarks

The ConvertACH method takes an industry-standard ACH file and converts it into an XML file. This XML can easily be viewed, edited, or otherwise manipulated. The ConvertXML method takes that modified XML and converts it back into an ACH file so that it can be processed.

The source XML can be specified by the SetInputStream method, or the InputFile and InputString properties, and the destination ACH file by the SetOutputStream method or the OutputFile and OutputString properties.

When the ConvertXML method is called, the source XML is validated in several ways. First, the XML format is validated. Unclosed tags and other editing mistakes will cause the class to be unable to parse the XML. The XML is then validated against the Schema. If any of the tags are missing or out of place, the class will be unable to parse the XML. Finally, each data field contained within an XML tag is then validated for the correct length and formatting (for instance, a character in an integer-only field will cause the class to fail with an error).

In addition, each XML file contains several Batch Control records and a final File Control Record. These records contain information about the transactions contained within the XML-formatted ACH file's Detail Records. The data contained within these control records is used to make sure the ACH files have not been corrupted, and have not lost records in the transmission process.

If you have made changes to the XML and you do not wish to manually compute the new Debit Total, Credit Total, Entry Count, and Entry Hash for each Batch Control record in the XML, you can set VerifyMode to vmComputeTotals, and allow the class to compute these values for you.

Reset Method (Achconverter Class)

Reset the internal state of the class and all properties to their default values.

Syntax

public void reset();

Remarks

The Reset method doesn't have any parameters and doesn't return any value.

SetInputStream Method (Achconverter Class)

The input stream to read from when calling ConvertXML or ConvertACH .

Syntax

public void setInputStream(java.io.InputStream inputStream);

Remarks

This property should contain the stream ConvertXML or ConvertACH will read from. If you do not wish to use a stream, you may specify an InputFile, or simply set the data in memory in the InputString property. If multiple inputs are specified, the source used will be selected in the following priority: SetInputStream, InputFile, and then InputString.

SetOutputStream Method (Achconverter Class)

The output stream to write to when calling ConvertXML or ConvertACH .

Syntax

public void setOutputStream(java.io.OutputStream outputStream);

Remarks

This property should contain the stream you wish the output from ConvertXML or ConvertACH to be written to. If you do not wish to use a stream, you may specify a OutputFile, or simply retrieve the data in memory from the OutputString property. If SetOutputStream and OutputFile are both specified, SetOutputStream takes precedence. OutputString will only be filled if both SetOutputStream and OutputFile are empty.

Error Event (Achconverter Class)

Information about errors during data delivery.

Syntax

public class DefaultAchconverterEventListener implements AchconverterEventListener {
  ...
  public void error(AchconverterErrorEvent e) {}
  ...
}

public class AchconverterErrorEvent {
  public int errorCode;
  public String description;
}

Remarks

The Error event is fired in case of exceptional conditions during message processing.

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

Config Settings (Achconverter Class)

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

ACHConverter Config Settings

CloseStreamAfterConversion:   If true, the component will close the output stream after conversion. This property is true by default. Therefore, by default, the output stream will be closed after conversion is completed. In order to keep streams open after the conversion completes, you must set this config to false.

Base Config Settings

BuildInfo:   Information about the product's build. When queried, this setting will return a string containing information about the product's build.

GUIAvailable:   Tells the class whether or not a message loop is available for processing events. In a GUI-based application, long-running blocking operations may cause the application to stop responding to input until the operation returns. The class will attempt to discover whether or not the application has a message loop and, if one is discovered, it will process events in that message loop during any such blocking operation. In some non-GUI applications, an invalid message loop may be discovered that will result in errant behavior. In these cases, setting GUIAvailable to false will ensure that the class does not attempt to process external events.

LicenseInfo:   Information about the current license. When queried, this setting will return a string containing information about the license this instance of a class is using. It will return the following information: Product: The product the license is for. Product Key: The key the license was generated from. License Source: Where the license was found (e.g., RuntimeLicense, License File). License Type: The type of license installed (e.g., Royalty Free, Single Server). Last Valid Build: The last valid build number for which the license will work.

MaskSensitive:   Whether sensitive data is masked in log messages. In certain circumstances it may be beneficial to mask sensitive data, like passwords, in log messages. Set this to true to mask sensitive data. The default is true. This setting only works on these classes: AS3Receiver, AS3Sender, Atom, Client(3DS), FTP, FTPServer, IMAP, OFTPClient, SSHClient, SCP, Server(3DS), Sexec, SFTP, SFTPServer, SSHServer, TCPClient, TCPServer.

UseDaemonThreads:   Whether threads created by the class are daemon threads. If set to True (default), when the class creates a thread, the thread's Daemon property will be explicitly set to True. When set to False, the class will not set the Daemon property on the created thread. The default value is True.

UseInternalSecurityAPI:   Tells the class whether or not to use the system security libraries or an internal implementation. When set to false, the class will use the system security libraries by default to perform cryptographic functions where applicable. Setting this setting to true tells the class to use the internal implementation instead of using the system security libraries. This setting is set to false by default on all platforms.

Trappable Errors (Achconverter Class)