Before you use the Automatic Bank Transmission feature, you need to implement a Java class so the bank transmission programs listed in the following table can successfully transmit files.
These programs require a Java class to provide logic for transmitting data to and from your specific bank. You need to implement one Java class per bank transmission setup.
This document refers to the Java class you need to implement as the Bank class.
Note: Oracle Payables and Oracle Cash Management provide a limited number of predefined Java Bank classes. Check Oracle Support's website, MetaLink, to see if a predefined Java class exists for your bank. Even if we don't provide a Bank class that meets your specific needs, you might find a predefined bank transmission setup helpful as a reference during your implementation.
This document describes what the transmission programs do and the logic that they require your Bank class to provide. This document provides a list of the predefined hashtable parameters that your Bank class can use, and it provides some guidance on how to implement your Bank class.
This document assumes you have a working knowledge of writing Java code.
This document also assumes you have already read the following documentation:
Defining Bank Transmission Details, Oracle Cash Management User Guide
Automatic Bank Transmission Feature, Oracle Cash Management User Guide
Retrieving Bank Statements and Payment Exceptions, Oracle Cash Management User Guide
Transmission programs require the following to successfully transmit a file:
Transmission Code Setup: These are transmission details, provided by your bank, that you enter in the Bank Transmission Details window. Transmission programs and the Bank class use these details to communicate with the specific bank. Details include information such as your bank's host address, password, transmission protocol, and file naming conventions. In the Bank Transmission Details window, you also specify in the Program field the Bank class that you have implemented for this particular bank setup. For more information on transmission codes, see: Bank Transmission Details Window Reference, Oracle Cash Management User Guide.
Bank class. This class that you implement contains five methods. Each method contains code to perform specific tasks for one transmission program. For example, one method contains all the detailed logic to transmit the payment file to your bank. The Bank class uses the transmission code information to complete its tasks. For example, when a Java method accesses the bank's system it uses the username and password that are specified in the transmission code.
When a transmission program submits, it is assigned a specific transmission code as a parameter. When a transmission program requires custom logic, it instantiates the Bank class specified in the Program field of the specified transmission code. The transmission program then calls the method that it requires. The method performs the required tasks and provides a parameter back to the program that says if the method completed successfully or not.
We provide the following template of a Java class that you can copy and use as a starting point to define the transmission logic for your bank.
$AP_TOP/java/transmission/BankClassTemplate.txt
It includes comments that provide additional guidance on how to implement your Bank class.
Each Bank class you implement must contain the following components:
Package Statement. Use the following package statement. Do not edit it:
package oracle.apps.ap.transmission;
Import Statement: Use the following import statement. Do not edit it:
import java.io.; import java.sql.; import java.util.Hashtable; import java.util.StringTokenizer; import java.util.Vector; import oracle.apps.fnd.common.VersionInfo;
Definition of Class Name: Name the Bank Java class. You will enter this name in the Program field in the Bank Transmission Details window. We suggest you use the name of your bank. Or, if you are defining multiple classes for the same bank we suggest you use your bank name with a unique suffix. Use the following syntax and replace "<classname>" with the name of your class:
public class <classname> extends Bank
Constructor: Define a bodiless constructor.
Methods: You need to implement the methods that are used by the transmission programs that you use. Each method must perform its required tasks for your particular bank.
public void ModifyPayment File (Hashtable): This method should contain the logic that the Transmit Payment File Program needs to modify the payment file that Payables creates, according to your bank's specifications. Payment file modifications might include adding text, formatting, and encryption. If you do not need to modify the payment file, then leave this method in the template unedited.
public void SendPayment File (Hashtable): This method should contain all the transmission logic that the Transmit Payment File Program uses to send the payment file from your local directory to your bank according to your bank's communication protocol.
public void ReceiveConfirmation (Hashtable): This method should contain all the transmission logic that the Retrieve Payment File Confirmations Program uses to retrieve payment file receipt confirmation files from your bank, and then store them in a local directory.
public void ReceiveStatement(Hashtable): This method should contain all the transmission logic that the Retrieve (Intra-Day) Bank Statement Program uses to retrieve (intra-day) bank statements from your bank, and then store them in a local directory.
public void ReceiveException(Hashtable): This method should contain all the transmission logic that the Retrieve Payment Exceptions Program uses to retrieve payment exception reports from your bank, and then store them in a local directory.
The Bank class should not directly read or update data in the application database tables. The Bank class should use the hashtable predefined parameters to access all necessary information from your Oracle application. The tables below show the read-only and writable hashtable parameters that your methods can use.
Methods should use read-only parameters to retrieve all necessary information from your Oracle application.
For example, to access the directory that contains the payment file you are sending to your bank, you can use the PaymentLocalDirectory parameter in the following syntax:
mPaymentFileDir = table.get ( "PaymentLocalDirectory" ) .toString () ;
The following table shows the read-only parameters that are available to your methods. The methods must never overwrite any of these parameter values. Many of these values are from the transmission code definition. The column names of the AP_TRANSMISSIONS_SETUP table correspond to fields in the Bank Transmission Details window with similar names. For more information on those fields, see: Bank Transmission Details Window Reference, Oracle Cash Management User Guide.
| Read-only Parameter Name in Hashtable | Comments |
|---|---|
| TransmissionId | AP_TRANSMISSIONS_SETUP.TRANSMISSION_ID |
| TransmissionCode | AP_TRANSMISSIONS_SETUP.TRANSMISSION_CODE |
| BankBranchId | AP_TRANSMISSIONS_SETUP.BANK_BRANCH_ID |
| TransmissionProgram | AP_TRANSMISSIONS_SETUP.TRANSMISSION_PROGRAM |
| UserName | AP_TRANSMISSIONS_SETUP.USERNAME |
| Password | AP_TRANSMISSIONS_SETUP.PASSWORD |
| Protocol | AP_TRANSMISSIONS_SETUP.PROTOCOL |
| ProtocolAddress | AP_TRANSMISSIONS_SETUP.PROTOCOL_ADDRESS |
| ExternalIdentifier | AP_TRANSMISSIONS_SETUP.EXTERNAL_IDENTIFIER |
| TransmissionEmail | AP_TRANSMISSIONS_SETUP.TRANSMISSION_EMAIL |
| ConfirmationEmail | AP_TRANSMISSIONS_SETUP.CONFIRMATION_EMAIL |
| PaymentLocalDirectory | AP_TRANSMISSIONS_SETUP.LOCAL_PAY_DIRECTORY |
| ConfirmationLocalDirectory | AP_TRANSMISSIONS_SETUP.LOCAL_CONF_DIRECTORY |
| BankPayDirectory | AP_TRANSMISSIONS_SETUP.BANK_PAY_DIRECTORY |
| ConfirmationBankDirectory | AP_TRANSMISSIONS_SETUP.BANK_CONF_DIRECTORY |
| PayFileExt | AP_TRANSMISSIONS_SETUP.PAY_FILE_EXT |
| PayFilePrefix | AP_TRANSMISSIONS_SETUP.PAY_FILE_PREFIX |
| PayFileSuffix | AP_TRANSMISSIONS_SETUP.BANK_FILE_SUFFIX |
| ConfirmationFileExt | AP_TRANSMISSIONS_SETUP.CONF_FILE_EXT |
| ConfirmationFilePrefix | AP_TRANSMISSIONS_SETUP.CONF_FILE_PREFIX |
| ConfirmationFileSuffix | AP_TRANSMISSIONS_SETUP.CONF_FILE_SUFFIX |
| StatementEmail | AP_TRANSMISSIONS_SETUP.STATEMENT_EMAIL |
| ExceptionEmail | AP_TRANSMISSIONS_SETUP.EXCEPTION_EMAIL |
| IntraEmail | AP_TRANSMISSIONS_SETUP.INTRA_STATEMENT_EMAIL |
| StatementLocalDirectory | AP_TRANSMISSIONS_SETUP.LOCAL_STMT_DIRECTORY |
| ExceptionLocalDirectory | AP_TRANSMISSIONS_SETUP.LOCAL_EXCEPTION_DIRECTORY |
| IntraLocalDirectory | AP_TRANSMISSIONS_SETUP.LOCAL_INTRA_DIRECTORY |
| StatementBankDirectory | AP_TRANSMISSIONS_SETUP.BANK_STMT_DIRECTORY |
| ExceptionBankDirectory | AP_TRANSMISSIONS_SETUP.BANK_EXCEPTION_DIRECTORY |
| IntraBankDirectory | AP_TRANSMISSIONS_SETUP.BANK_INTRA_DIRECTORY |
| StatementFilePrefix | AP_TRANSMISSIONS_SETUP.STMT_FILE_PREFIX |
| ExceptionFilePrefix | AP_TRANSMISSIONS_SETUP.EXCEPTION_FILE_PREFIX |
| IntraFilePrefix | AP_TRANSMISSIONS_SETUP.INTRA_FILE_PREFIX |
| StatementFileSuffix | AP_TRANSMISSIONS_SETUP.STMT_FILE_SUFFIX |
| ExceptionFileSuffix | AP_TRANSMISSIONS_SETUP.EXCEPTION_FILE_SUFFIX |
| IntraFileSuffix | AP_TRANSMISSIONS_SETUP.INTRA_FILE_SUFFIX |
| StatementFileExt | AP_TRANSMISSIONS_SETUP.STMT_FILE_EXT |
| ExceptionFileExt | AP_TRANSMISSIONS_SETUP.EXCEPTION_FILE_EXT |
| IntraFileExt | AP_TRANSMISSIONS_SETUP.INTRA_FILE_EXT |
| CONNECTION | Stores database connection information |
| FileName | Stores payment file name in progress. Used only by the Transmit Payment File Program |
| RequestId | Stores the request ID of the concurrent program |
The Bank class must use hashtable predefined writable parameters to return the status of each method to the transmission program that called the method. For example, to tell the Send Payment File transmission program that the method that modifies the payment file successfully completed, you could use the following syntax:
table.put ( "ModifyPaymentFileStatus",Boolean.TRUE) ;
The following table shows the parameters that each method is expected to write to.
| Writable Parameter Name in Hashtable | Method Expected to Write to This Parameter | Comments |
|---|---|---|
| ModifyPaymentFile Status | public void ModifyPayment File (Hashtable) | Boolean value of TRUE or FALSE depending on whether the method was successful |
| SendPaymentFileResult | public void SendPayment File (Hashtable) | Boolean value of TRUE or FALSE depending on whether the method was successful |
| ReceiveFileResult | public void ReceiveConfirmation (Hashtable) | Boolean value of TRUE or FALSE depending on whether the method was successful |
| DownloadedFilesVector | public void ReceiveConfirmation (Hashtable) | This vector holds the names of all the confirmation files that the program retrieves |
| ReceiveFileResult | public void ReceiveStatement (Hashtable) | Boolean value of TRUE or FALSE depending on whether the method was successful |
| ReceiveFileResult | public void ReceiveException (Hashtable) | Boolean value of TRUE or FALSE depending on whether the method was successful |
| DownloadedFilesVector | public void ReceiveStatement (Hashtable) | This vector holds the names of all the statement files that the program retrieves |
| DownloadedFilesVector | public void ReceiveException (Hashtable) | This vector holds the names of all the exception files that the program retrieves |
Each bank class method must handle all exceptions that might occur during execution of the method. The following are examples of exceptions that your methods might encounter:
The method is trying to connect to the bank's directory and the bank does not accept the password.
The method cannot connect to a specified directory at the bank.
If the method fails, the method must write to the method's status parameter with a value of FALSE. The list of these status parameters is in the previous section, Required, Writable Parameters.
You can use the Utilities.WriteLogFile function if you want to log error messages in the log file of the transmission program that called the method. You can do this either for your own debugging or to provide guidance to users who submit the transmission program.
The following is an example of syntax you could use in the method that sends the payment file to the bank:
if(communicationProtocol.send())
table.put("SendPaymentFileResult", Boolean.TRUE);
else
{
Utilities.WriteLogFile( "Unable to send payment file." );
table.put("SendPaymentFileResult", Boolean.FALSE);
This section describes the Java methods you need to implement and describes when they are called by the transmission programs. These methods need to perform exactly the tasks described.
Each method has access to all the parameter values in the hashtable. See: Communication Between the Bank class and the Bank Transmission Programs. Methods should not overwrite the values of the read-only parameters.
This program calls two bank class methods, one method optionally modifies the payment file and the other method transmits the payment file to your bank.
The system performs the following in the following order when a user formats a payment batch or Quick payment that uses a payment document that is set up for Automatic Bank Transmission:
The format payment program creates a record in the AP_BANK_TRANSMISSIONS table with a status of NEW. The record contains payment file information and bank details from the transmission code.
A Payment Formatted event is raised to the Workflow Business Events System. This initiates the Transmit Payment File Program.
The Transmit Payment File Program then copies the payment file to the local directory, and calls the public void ModifyPayment File (Hashtable) method.
The Transmit Payment File Program, which sends a payment file to your bank, calls this method to modify the payment file that Payables creates. Modifications might include adding text, formatting, or encryption. If your bank does not need the payment file to be modified, then copy this method from the template and do not edit it.
This method should do the following, in the following order:
Modify the payment file in the local directory according to your bank's specifications, if your bank requires it.
Return a value in the ModifyPaymentFileStatus parameter indicating if the modification succeeded or failed
If the method succeeds then the Transmit Payment File Program updates the record status to MODIFIED,. If the method fails, then the program updates the record status to MODIFY ERROR.
The Transmit Payment File Program expects this method to provide a Boolean value for the ModifyPaymentFileStatus parameter. The value should be TRUE if the method succeeds, and FALSE if the method fails.
If you do not edit this method in the template, then the method simply returns a value to this parameter of TRUE so that the Transmit Payment File Program can continue without modifying the payment file.
This method should contain all the transmission logic that the Transmit Payment File Program uses to send a payment file to your bank.
After the Transmit Payment File Program updates the payment file record to MODIFIED, it calls the public void SendPayment File (Hashtable) method.
This method should do the following in the following order:
Send the modified payment file from the local directory to your bank.
Return a value in the SendPaymentFileResult parameter indicating whether the transmission succeeded or failed.
If this method completes successfully, the Transmit Payment File Program updates the status of the payment file record in the AP_BANK_TRANSMISSION table to SENT. The Transmit Payment File Program then uploads the modified payment file to the CLOB column in AP_BANK_TRANSMISSIONS.
If this method fails, the Transmit Payment File Program updates the record status to TRANSMISSION ERROR.
The workflow then automatically sends an e-mail notification to the workflow role specified in the payment document's transmission code stating whether the transmission succeeded or failed.
If this method fails then the user must cancel the payment batch or Quick payment and start over, because this feature does not include resend functionality.
The Transmit Payment File Program expects this method to provide a Boolean value for the SendPaymentFileResult parameter. The value should be TRUE if the method successfully sends the payment file to your bank, and FALSE if the method fails.
This method should contain all the transmission logic that the Retrieve Payment File Confirmations Program uses to retrieve payment receipt confirmation files from your bank and store them in a local directory.
When a user initiates the Retrieve Payment File Confirmations Program in the Submit Request window, the user specifies the bank's transmission code as a program parameter. The Retrieve Payment File Confirmations Program then calls this method.
This method should do the following in the following order:
Retrieve all confirmations that are in the bank's remote directory exactly once. This method must guarantee that once a file is copied that it is never copied again.
Store all the confirmation files in the local directory specified by the ConfirmationLocalDirectory parameter.
Store the names of all the retrieved confirmation files in the DownloadFilesVector.
Return a value in the ReceiveFileResult parameter indicating if the retrieval of the confirmation files succeeded or failed.
The Retrieve Payment File Confirmations Program then sends an e-mail to the workflow role specified in the Confirmation Recipient E-mail field for the transmission code. This e-mail tells the user whether the payment confirmation retrieval succeeded or failed. If retrieval is successful then the e-mail also includes a list of the confirmation files.
The Receive Payment Confirmations Program expects this method to provide a Boolean value for the ReceiveFileResult parameter. The value should be TRUE if the method is successful, and FALSE if the method fails.
The Receive Payment Confirmations Program expects this method to store the names of the files that were retrieved from the bank in this vector parameter.
The following is a sample of the code structure you can use for this method. However, you can code this using your own coding standards:
Vector fileNamesVector = new Vector();
while (xxxxxx)
{
<<<<<<<<Receive logic>>>>>>>>>>
//add downloaded file to the vector
fileNamesVector.addelement(fileName);
}
tables.put("DownloadedFilesVector", fileNamesVector);
table.put("ReceiveFileResult", Boolean.TRUE);
In the code sample above, the "while" logic example is used to store the name of the downloaded files in the required vector, "fileNamesVector". You can use your own logic to store the downloaded file names in DownloadedFilesVector, or see: Example Coding for fileNamesVector for an example.
This method should contain all the transmission logic that the Retrieve (Intra-Day) Bank Statement Program uses to retrieve (intra-day) bank statements from your bank and store them in a local directory. When a user initiates the Retrieve (Intra-Day) Bank Statement Program in the Submit Request window, the user specifies the bank's transmission code as a program parameter.
The Retrieve (Intra-Day) Bank Statement Program then calls this method. This method should do the following in the following order:
Retrieve all (intra-day) bank statements that are in the bank's remote directory exactly once. This method must guarantee that once the file is copied that it is never copied again.
Store all the (intra-day) bank statements in the local directory specified by the StatementLocalDirectory/IntraLocalDirectory parameter.
Store the names of all the retrieved (intra-day) bank statements in the DownloadedFilesVector.
Return a value in the ReceiveFileResult parameter indicating if the retrieval of the (intra-day) bank statements succeeded or failed.
The Retrieve (Intra-Day) Bank Statement Program then sends an e-mail to the user represented by the workflow role specified in the Statement e-mail address for the transmission code. This e-mail tells the user whether the (intra-day) bank statement retrieval succeeded or failed. If retrieval is successful then the e-mail also includes the file names of the (intra-day) bank statements.
The Retrieve (Intra-Day) Bank Statement Program expects this method to provide a Boolean value for the ReceiveFileResult parameter. The value should be TRUE if the method is successful, and FALSE if the method fails.
The Retrieve (Intra-Day) Bank Statement Program expects this method to store the names of the files that were retrieved from the bank in this vector parameter.
The following is a sample of the code structure you can use for this method. However, you can code this using your own coding standards:
Vector fileNamesVector = new Vector();
while (xxxxxx)
{
<<<<<<<<Receive logic>>>>>>>>>>
//add downloaded file to the vector
fileNamesVector.addelement(fileName);
}
tables.put("DownloadedFilesVector", fileNamesVector);
table.put("ReceiveFileResult", Boolean.TRUE);
In the code sample above, the "while"logic example is used to store the name of the downloaded files in the required vector, "fileNamesVector". You can have your own logic to store the downloaded file names in DownloadedFilesVector, or see: Example Coding for fileNamesVector for an example.
This method should contain all the transmission logic that the Retrieve Payment Exceptions Program uses to retrieve payment exception reports from your bank and store them in a local directory.
When a user initiates the Retrieve Payment Exceptions Program in the Submit Request window, the user specifies the bank's transmission code as a program parameter. The Retrieve Payment Exceptions Program then calls this method.
This method should do the following in the following order:
Retrieve all payment exception reports that are in the bank's remote directory exactly once. This method must guarantee that once the file is copied that it is never copied again.
Store all the bank statements in the local directory specified by the ExceptionLocalDirectory parameter.
Store the names of all the retrieved payment exception reports in the DownloadedFilesVector.
Return a value in the ReceiveFileResult parameter indicating if the retrieval of the payment exception reports succeeded or failed.
The Retrieve Payment Exceptions Program then sends an e-mail to the user represented by the workflow role specified in the Exception e-mail address for the transmission code. This e-mail tells the user whether the payment exception report retrieval succeeded or failed. If retrieval is successful then the e mail also includes a list of payment exception reports.
The Retrieve Payment Exceptions Program expects this method to provide a Boolean value for the ReceiveFileResult parameter. The value should be TRUE if the method is successful, and FALSE if the method fails.
The Retrieve Payment Exceptions Program expects this method to store the names of the files that were retrieved from the bank in this vector parameter.
The following is a sample of the code structure you can use for this method. However, you can code this using your own coding standards:
Vector fileNamesVector = new Vector();
while (xxxxxx)
{
<<<<<<<<Receive logic>>>>>>>>>>
//add downloaded file to the vector
fileNamesVector.addelement(fileName);
}
tables.put("DownloadedFilesVector", fileNamesVector);
table.put("ReceiveFileResult", Boolean.TRUE);
In the code sample above, the "while" logic example is used to store the name of the downloaded files in the required vector, "fileNamesVector". You can use your own logic to store the downloaded file names in DownloadedFilesVector, or see: Example Coding for fileNamesVector for an example.
DownloadedFilesVector is a vector of vector. The first element of the internal vector is the string file name. The second level vector is implemented to associate extra attributes about the file in the second element forward, such as isFileMeaningful. Below is a sample of how the file ABCDBank.java implements the code:
StringTokenizer st =
new StringTokenizer( (String)table.get( "ResultStatement" ) );
.
while(st.hasMoreTokens())
{
String fileName = st.nextToken();
Utilities.WriteLogFile( "token = " + fileName );
.
if( fileName.startsWith( beginsWith )
&&
fileName.endsWith( endsWith ) )
{
table.put( type + "FileName", fileName );
Utilities.WriteLogFile( "receveing fileName = " + fileName );
............
//************* RELEVANT CODE BEGIN ****************
.
//a vector of file name and other attributes if required
Vector fileName = new Vector();
fileName.addElement( downloadedFileName );//java.lang.String,
attribute required
fileName.addElement( isFileMeaningful );//java.lang.Boolean,
attribute not required
fileName.addElement( <other attributes> );
.
//add fileName Vector to Vector that gets inserted in hashtable
fileNamesVector.addElement( fileName );
.
//************* RELEVANT CODE END ****************
............
}//while
.
//add fileName Vector to the hastable key as a Vector
table.put( "DownloadedFilesVector", fileNamesVector );
Get all the information you need from your bank to complete the fields in the Bank Transmission Details window.
Review this document and then get all the information you need to write the Java methods.
Define the local directories that you use for the local payment file and the local confirmation file (which you specify in the Bank Transmission Details window) in the utl_file_dir parameter of the init.ora file.
Copy the Bank class template: $AP_TOP/patch/115/readme/BankClassTemplate.txt.
Give the Bank class a unique name.
Tip: Use your bank name as the name of the Bank class. If you have more than one transmission setup for the same bank, and you define more than one Bank class for a bank, then name each class after the bank and add a distinguishing suffix to the file name.
Implement the Java methods that are called by programs you use. Include any exception handling.
Compile your code.
Make sure that the .class file you generate is in a directory specified by the $CLASSPATH variable of the operating system.
Complete the fields in the Bank Transmission Details window.
In the Program field of the Bank Transmission Details window enter the name of your Bank class. This field is case-sensitive.
Test your code.