Skip Headers

Oracle Payables Implementation Guide
Release 12.1
Part Number E12795-04
Go to Table of Contents
Contents
Go to previous page
Previous
Go to next page
Next

Implementing the Java Bank Class

Implementing the Java Bank Class for Bank Transmissions

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.

Transmission Program Application Short Name
Transmit Payment File Program Payables APXTRSND
Retrieve Payment File Confirmations Program Payables APXTRRCV
Retrieve Bank Statement Program Cash Management CEXP2PSM
Retrieve Intra-Day Bank Statement Program Cash Management CEP2PINT
Retrieve Payment Exceptions Program Cash Management CEXP2PER

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.

Document Assumptions

This document assumes you have a working knowledge of writing Java code.

This document also assumes you have already read the following documentation:

Relationship of the Transmission Programs, Transmission Code Setup, and the Bank Class

Transmission programs require the following to successfully transmit a file:

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.

The Bank Class Template

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.

What You Need to Include in Your Bank Class

Each Bank class you implement must contain the following components:

Communication Between the Bank Class and the Bank Transmission Programs

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.

Read-only Parameters

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
   

Required, Writable Parameters

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

Error Handling

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:

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);

Bank Class Method Descriptions

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.

Transmit Payment File Program

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:

public void ModifyPayment File (Hashtable):

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:

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.

ModifyPaymentFileStatus parameter

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.

public void SendPayment File (Hashtable):

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:

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.

SendPaymentFileResult parameter

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.

public void ReceiveConfirmation (Hashtable):

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:

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.

ReceiveFileResult parameter

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.

DownloadedFilesVector parameter

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.

Sample code structure for this method

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.

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 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:

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.

ReceiveFileResult parameter

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.

DownloadedFilesVector parameter

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.

Sample code structure for this method

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.

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 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:

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.

ReceiveFileResult parameter

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.

DownloadedFilesVector parameter

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.

Sample code structure for this method

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.

Example Coding for fileNamesVector

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 ); 
 

Bank Class Setup

Prerequisites

To implement a Bank class:

  1. Copy the Bank class template: $AP_TOP/patch/115/readme/BankClassTemplate.txt.

  2. 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.

  3. Implement the Java methods that are called by programs you use. Include any exception handling.

  4. Compile your code.

  5. Make sure that the .class file you generate is in a directory specified by the $CLASSPATH variable of the operating system.

  6. 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.

  7. Test your code.