Implementation Guide for Oracle Billing Insight > Customizing Payment >

Customizing Oracle Billing Insight Payment Template Files

Oracle Billing Insight provides a template engine to generate text messages, such as email, ACH files, and A/R files. This topic describes how to use Oracle Billing Insight Payment templates to customize those text messages.

Oracle Billing Insight Payment Template Engine

The Oracle Billing Insight Payment templates provide a generic template mechanism based on Java reflection. The template engine generates custom text output based on the templates. Similar to JSP, the template engine replaces the special placeholders inserted into the text file with the values of Java objects. For more detailed API documentation, see Accessing Oracle Billing Insight Data Dictionary and Javadoc for details on accessing Oracle Billing Insight Javadoc.

The Template engine hosts a pool of objects in its context in the form of a hash table. You can refer to the variables in that context by their names. For example, there is a Check object whose name is check. You can refer to that object as %check%. This means replace %check% with the string returned from check.toString(). This is true for all Java objects except java.util.Date, where getTime() is called and inserts a long value that is the number of milliseconds since January 1, 1970, 00:00:00 GMT. If a method returns void, then nothing prints.

The content of the message consists of text plus resolved placeholders. Placeholders are Java variables, which are Payment hosted objects including their attributes and methods.

Enclose all template variables with two percent signs (%%). To escape %, use %%. For example, %%40 means %40.

In addition to referring to variables, you can also access an object's public fields and methods. The valid reference is %name.field%, %name.method(param1, param2, ...)%. Each parameter to a method can be name, name.field, or name.method(param1, param2, ,,,). The number of parameters is unlimited and an arbitrary level of method nesting is allowed (nesting means that a method's return value is used as a parameter when calling another method). For example, suppose there are two objects in contexts: buf which is a StringBuffer, and str which is a String. The following references are valid:

%buf%, %buf.append(str)%, %buf.append(str.toString())%

A static field or method can be accessed directly without instantiating an object. For example, java.lang.Integer has a static field called MIN_VALUE and a static method called parseInt. You can refer to them as %java.lang.Integer.MIN_VALUE% or %java.lang.Integer.parseInt("12.34")%.

All variables must be preset by calling putToContext on the Template class. Some variables are already set by Oracle Billing Insight Payment which you can use directly. But you can also put your own variables into the context:

%template.putToContext("buf", new java.lang.StringBuffer())%

This means to put a new StringBuffer object called buf into the template context. You can then refer to this object by its name:

%buf.append("abc")%

This appends "abc" to the end of the StringBuffer's value.

The Oracle Billing Insight Payment engine has some limitations. It cannot do math operations, such as x plus y. You must call a Java method to do math operations. Another limitation is that it does not allow you to concatenate method calls, for example: %variable.method().method() %. You must write your own Java method to do method concatenation.

Included with the Oracle Billing Insight Payment package, there are a few utility classes to help you overcome the weakness of Oracle Billing Insight Payment Template Engine. These classes are:

com.edocs.common.payment.util.DecimalUtil
com.edocs.common.payment.util.DateUtil
com.edocs.common.payment.util.StringUtil.

One useful method in StringUtil is concat, which you declare and use as follows:

public static String concat(String s1, String s2, String s3)
%com.edocs.common.payment.util.StringUtil.concat(s1,s2,s3)%

Remember, you cannot do %s1.concat(s2).concat(s3)% inside a template, instead, you must call this function from template:

%com.edocs.common.payment.util.StringUtil.concat(s1,s2,s3)%.

Another useful method is format() from DateUtil class. This method helps format a Date object into different display formats. For example: %com.edocs.common.payment.util.DateUtil.format("MMM dd, yyyy", check.getPayDate())% formats a check's pay date to display as "Jan 01, 2000." For a complete list of possible date formats, please check the JDK document about java.text.SimpleDateFormat.

When writing customized Java code, it is strongly recommended that you use static methods as frequently as possible, so you can call them directly from a template without creating an instance of that object first. For example, by default, the individual ID field of an ACH entry detail field is populated with the customer's account number using %check.getPayerAcctNumber()%. The returned result is 16 bytes long, but the account number is 15 bytes, so you must truncate the retrieved value.

To create a Java class to do truncation and enable it in the Oracle Billing Insight Payment Template Engine

1. Write a Java class:

   package com.edocs.common.ps;
   public class MyUtil {
   public static String truncate(String s){
   return s.substring(1);
   }
   }

2. Compile the class and put it into the Payment_custom.jar of each EAR file, then redeploy the EAR files.
3. Refer to this class in a template as follows:

   %com.edocs.common.ps.MyUtil.truncate(check.getPayerAcctNumber())%

Oracle Billing Insight Payment Reminder Template

Oracle Billing Insight Payment reminder messages are generated based on the following notification types, and are defined in the notification template file:

• PaymentScheduledNotification
• PaymentSuccessNotification
• PaymentFailureNotification

PaymentReminder.txt, which resides in the EDX_HOME/config/notification/templates/ directory (the EDX_HOME\onfig\notification\templates directory on Windows). In the path, EDX_HOME is the directory where you installed Oracle Billing Insight.

This template is used for email notifications for processed, returned or failed payments.

Enrollment Notification Template

The enrollment notification template notifies customers about active and bad-active payment accounts and NOC returns. Enrollment reminder messages are generated based on the notification type PaymentNotifyEnrollNotification, which is defined in the notification template file.

This template is used for ACH. The parameter "isACH" is for ACH. If there are no payment gateways for ACH, then you can remove that topic from the template file.

Each Oracle Billing Insight Payment account is sent an individual email. Oracle Billing Insight Payment supports multiple payment accounts. If a customer has multiple payment accounts, then there could be more than one email message sent for each customer.

The variables described in Table 71 apply to ACH.

The variables described in Table 72 apply to ACH NOC returns.

Recurring Payment Schedule Notification Template

When recurring payment schedules a payment, email notification messages are generated from the notification type PaymentScheduledNotification, which is defined in the template file.

Customizing ACH Templates

The ACH records of interest are in File Header, Batch Header, Entry Detail for PPD, Addenda and return for PPD, Batch Trailer and File Trailer. ACH fields can be mandatory, required, or optional. The contents of mandatory fields are fixed and must not be customized. Required fields are usually defined by the receiving bank, and can be customized for different banks. Optional fields can be customized, also.

By default, secCode is set to WEB to be compliant with the ACH 2001 format. However, you can change the SEC code based on the requirements of a biller's bank by editing the batchHeader_template.xml file.

Table 73 describes some ACH fields. These fields can be customized upon a biller's request. The pmtCheckSubmit jobs running date is referred to as Today.

The templates for ACH are XML files, which describe the format of each ACH record, such as the start position, length, and so on. There are two sets of templates: one to generate ACH files, and another to parse ACH return files.

The first set of templates is used to generate the following ACH files:

• fileHeader_template.xml
• batchHeader_template.xml
• entryDetail_template.xml
• batchTrailer_template.xml
• Trailer_template.xml

When an ACH file is generated, check information is pulled from the database and then populated into the content of the XML files by replacing the template variables. The resulting XML file is transferred into an ACH file according to the format specified by the XML tags. The generic format of an XML tag is:

<amount pos="30" len="10" fmt="N" fract="2">%

where:

• amount is the name of the tag
• pos="30" is the start position
• len="10" is the length of the field
• fmt="N" is the format of the field
• fract="2" is the number of digits after the decimal point if the format (fmt) is N (numerical)

Table 74 through Table 78 list the template variables that are predefined in the Oracle Billing Insight Payment Template Engine. These variables are used to populate the content of the templates.

Table 74 describes the template variables that all templates use.

Table 75 describes the template variables that File Header uses.

Table 76 describes the template variables that Batch Header uses.

Table 77 describes the template variables that Entry Detail uses.

Table 78 describes the template variables that Batch Trailer uses.

Matching a Check in the ACH Return to the Database

Return files are parsed by the return templates:

• fileHeader_return_template.xml
• batchHeader_return_template.xml
• entryDetail_return_template.xml
• addenda_return_template.xml
• batchTrailer_return_template.xml
• fileTrailer_return_template.xml

The format of these files is similar to the format of the submit template. For example:

<individualName pos="55" len="22" fmt="AN" target="%check.setPaymentId(?)%"></individualName>

This code retrieves the part of the text from positions 55 to 77, puts it into a variable called ? and then calls check.setPaymentId() to set payment_id for the check. The template executes the template statement specified by XML tag "target" only.

When a check is returned from the ACH network, Oracle Billing Insight Payment matches it to that check in the database and marks it as returned. ACH modifies several fields in the return file. Oracle Billing Insight Payment populates one or more unchanged fields with identification information to help in matching them with a check in the database. Consult the ACH documentation for information about which fields are not changed.

The return template retrieves the error return code from the addenda record and then tries to reconstruct the payment ID or gateway payment ID to match a check in the database. If Oracle Billing Insight cannot populate the payment ID into the ACH file, then it uses the gateway payment ID, which is a concatenation of a few check payment fields that can identify a check.

By default, Oracle Billing Insight Payment populates the payment_id of the check into the individual name field to create the ACH file. The following line in the entryDetail_template.xml file populates the payment ID into an individual name:

<individualName pos="55" len="22" fmt="AN">%check.getPaymentId()%</individualName>

The following line in the entryDetail_return_template.xml file extracts the payment ID:

< individualName pos="55" len="22" fmt="AN" target="%check.setPaymentId(?)%"></individualName >

The following line in the addenda_return_template.xml file extracts the return error code:

<returnReasonCode pos="4" len="3" target="%check.setTxnErrMsg(?)%"></returnReasonCode>

Payment then changes the status of the check to returned and updates this check in the database using its payment_id.

If the individual name is required for another task, for example, the check account name (which is the first 22 bytes), then follow these steps to use gateway payment ID.

To use the gateway payment ID

1. Modify the entryDetail_template.xml file to populate individual name with account name. Change:

   <individualName pos="55" len="22" fmt="AN">%check.getPaymentId()%</individualName>

   to:

   <individualName pos="55" len="22" fmt="AN">%stringUtil.substring(check.getAccountName(), 0, 22)%</individualName>

2. Modify the entryDetail_return_template.xml file so that payment ID will not be set for a returned check. Change:

   <individualName pos="55" len="22" fmt="AN" target='%check.setPaymenId(?)%'></individualName>

   to:

   <individualName pos="55" len="22" fmt="AN"></individualName>

3. Because payment ID cannot be used to match checks, use the gateway payment ID instead. Gateway payment ID is the ID generated by the template that submitted the ACH file to ACH. This template generates a unique ID based on the information submitted to ACH. This ID must contain information that will not be changed by ACH in the return file. The Oracle Billing Insight engine uses the gateway payment ID to find a match in the database.

In very rare circumstances, more than one match might be found. In that case, the match with the latest creation time is used. The following example discusses several ways to generate the gateway payment ID. Oracle Billing Insight Payment generates a trace number and puts that into the entry detail record. By default, the trace number starts at 0000000 and increases by one for each check until it reaches 9999999. After this point, the numbering restarts at 0000000. It is possible to get a duplicate trace number (after 10 million checks). However, because the Oracle Billing Insight Payment engine always chooses the payment with the latest date, the correct check will be matched. You can use both the trace number and individual ID (customer account number) to identify a payment and use them for the gateway payment ID.

Example 1: Unchanged ACH Trace Number

In the following example, it is assumed that the ACH or Bank will return both the original trace number and individual ID to Oracle Billing Insight:

1. At the beginning of the entryDetail_template.xml file, find the following code:

   <ACH_6>
   %<*>%
   %check.setGatewayPaymentId(com.edocs.common.payment.util.StringUtil.concat(check.getPayerAcctNumber(), "_", check.getTxnNumber()))%

   %</*>%

   This statement is commented out in the template, using %<*>% and %</*>%. Removing the comment tags enables the statement.

   The trace number is stored as txnNumber in the check object. This statement concatenates the customer account number, a "_", and trace number as the gateway payment ID. The setGatewayPaymentId method returns void, so nothing will print out. (If it did return a value, then that would print, which would ruin the format of the XML file.) After running pmtCheckSubmit, check the gateway payment ID in the EDX_PMT_TRANSACTION table, which is the concatenation of the individual ID and the trace number that are written into the entry detail record.

2. Next, Payment retrieves the original trace number from the return file, and sets it as the gateway payment ID. In the addenda_return_template.xm, find this code:

   <traceNumber pos="80" len="15" fmt="N" target1='%check.setGatewayPaymentId(txnNumber)%' target2='%check.setGatewayPaymentId(stringUtil.concat(payerAcctNumber, "_", txnNumber))%'></traceNumber>

   Rename target2= to target, which will reconstruct the gateway payment ID based on the returned customer account number and trace number. Template variable payerAcctNumber has been set in the entryDetail_return_template.xml file and txnNumber has been set before this line in the addenda_return_template.xml file by calling template.putToContext.

3. Test this setting using a real return file, and verify that the check's status has been updated to -4 in the EDX_PMT_TRANSACTION table.

Example 2: Modified ACH Trace Number

If the individual ID is not returned as it was set, then you can try to use other information, such as individual name combined with trace number. If only the trace number can be used for gateway payment ID, then use that as follows.

To use only the trace number for gateway payment ID

1. At the beginning of the entryDetail_template.xml file, find the following code:

   %<*/>%
   %check.setGatewayPaymentId(check.getTxnNumber())%
   %</*>%

   Remove the comment tags to enable the statement.

2. In the addenda_return_template.xml file, rename target1 to target to enable using trace number as gateway payment ID:

   <traceNumber pos="80" len="15" fmt="N" target1='%check.setGatewayPaymentId(txnNumber)%' target2='%check.setGatewayPaymentId(stringUtil.concat(payerAcctNumber, "_", txnNumber))%'></traceNumber>