Implementation Guide for Oracle Self-Service E-Billing > Customizing Payment >

Customizing Oracle Self-Service E-Billing Payment Template Files

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

Oracle Self-Service E-Billing Payment Template Engine

The Oracle Self-Service E-Billing 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 Self-Service E-Billing Javadoc for details on accessing Oracle Self-Service E-Billing 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, ...)%, where 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 Self-Service E-Billing 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 current Oracle Self-Service E-Billing 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 Self-Service E-Billing Payment package, there are a few utility classes to help you overcome the weakness of Oracle Self-Service E-Billing Payment Template Engine. These classes are:

com.edocs.payment.util.DecimalUtil
com.edocs.payment.util.DateUtil
com.edocs.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.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.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.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 Self-Service E-Billing Payment Template Engine

1. Write a Java class:

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

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

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

Customizing Email Templates

The Payment module uses template files to generate customized text that will be sent in a notification email. The email templates can be customized for you by Oracle Professional Services, or you can customize them yourself.

Table 70 describes the email notification templates used in Payment.

For UNIX, the default path to the email template files is the EDX_HOME/payment/lib/payment_resources/ directory (the EDX_HOME\payment\lib\payment_resources directory on Windows). In the path, EDX_HOME is the directory where you installed Oracle Self-Service E-Billing.

The email templates use a programming structure that works similar to JSP (but is not JSP). The template language includes a list of placeholders that refers to Java objects, which are hosted by Payment. It also includes some logic control directives such as IF and LOOP.

For more information about template classes, see Accessing Oracle Self-Service E-Billing Javadoc for details on accessing Oracle Self-Service E-Billing Javadoc.

Oracle Self-Service E-Billing Payment Reminder Template

Oracle Self-Service E-Billing Payment reminder messages are generated based on PaymentReminder.txt, which resides in the EDX_HOME/payment/lib/payment_resources/ directory (the EDX_HOME\payment\lib\payment_resources directory on Windows). In the path, EDX_HOME is the directory where you installed Oracle Self-Service E-Billing.

This template is used for regular payment reminder and email notifications for processed, returned or failed payments.

Table 71 describes the Oracle Self-Service E-Billing Payment reminder template variables.

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 enrollNotify.txt.

This template is used for ACH. The text between %<IF isACH>% and the corresponding %</IF>% is for ACH. If there are no payment gateways for ACH, you can remove that topic from the template file.

Each Oracle Self-Service E-Billing Payment account will be sent an individual email. Oracle Self-Service E-Billing Payment supports multiple payment accounts. If a customer has multiple payment accounts, there could be more than one email message sent for each customer.

Table 72 list the variables available for use in the Enrollment Notification email template. The variables described in Table 72 apply to all cases.

The variables described in Table 73 apply to ACH.

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

Recurring Payment Schedule Notification Template

When recurring payment schedules a payment, email notification messages are generated from the template file recurringNotify.txt.

Table 75 describes the recurring notification template variables.

Payment Notification Template

This template controls the format of email that are sent to the administrator by each job. The template file is notifyPaymentTask.txt.

pmtCreditCardExpNotify Variables

Table 76 describes the payment notification template variables related to pmtCreditCardExpNotifiy.

pmtRecurringPayment Variables

Table 77 describes the recurring notification template variables for the synchronization task.

Table 78 describes the recurring notification template variables for the scheduler task.

pmtPaymentReminder Variables

Table 79 describes the pmtPaymentReminder variables.

pmtCreditCardExpNotify Variables

Table 80 describes the pmtCreditCardExpNotify variables.

pmtCheckSubmit Variables

Table 81 describes the pmtCheckSubmit variables.

pmtSubmitEnroll

Table 82 describes the pmtSubmitEnroll variables.

Credit Card Expiration Notification Template

When a credit card is about to expire, email notification messages are generated from the template file CCExpNotify.txt.

Table 83 describes the credit card expiration notification template variables.

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 84 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 85 through Table 89 list the template variables that are predefined in the Oracle Self-Service E-Billing Payment Template Engine. These variables are used to populate the content of the templates.

Table 85 describes the template variables that all templates use.

Table 86 describes the template variables that File Header uses.

Table 87 describes the template variables that Batch Header uses.

Table 88 describes the template variables that Entry Detail uses.

Table 89 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 Self-Service E-Billing Payment matches it to that check in the database and marks it as returned. ACH modifies several fields in the return file. Oracle Self-Service E-Billing 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 Self-Service E-Billing Payment cannot populate the payment ID into the ACH file, it uses the gateway payment ID, which is a concatenation of a few check payment fields that can identify a check.

By default, Oracle Self-Service E-Billing 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 Self-Service E-Billing 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 Self-Service E-Billing 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 Self-Service E-Billing 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 Self-Service E-Billing:

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

   <ACH_6>
   %<*>%
   %check.setGatewayPaymentId(com.edocs.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 check_payments 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. Now you are all set. Test this setting using a real return file and verify that the check's status has been updated to -4 in the check_payments table.

Example 2: Modified ACH Trace Number

If the individual ID is not returned as it was set, 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, use that as follows.

To use only the trace number for gateway payment ID

1. At the beginning of the entryDetail_template.xml file, see 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>