In this section, we describe how to set up the user-defined algorithms that perform many important functions including:
· Validating the format of a phone number entered by a user.
· Validating the format of a latitude/longitude geographic code entered by a user.
· In Oracle Utilities Customer Care and Billing:
· Calculating late payment charges.
· Calculating the recommended deposit amount.
· Constructing your GL account during the interface of financial transactions to your GL
· And many other functions...
Contents
Many functions in the system are performed using a user-defined algorithm. For example, when a CSR requests a customer’s recommended deposit amount, the system calls the deposit recommendation algorithm. This algorithm calculates the recommended deposit amount and returns it to the caller.
Algorithm = Plug-in. We use the terms plug-in and algorithm interchangeably throughout this documentation.
So how does the system know which algorithm to call? When you set up the system’s control tables, you define which algorithm to use for each component-driven function. You do this on the control table that governs each respective function. For example:
· You define the algorithm used to validate a phone number on your phone types.
· You define the algorithm in Oracle Utilities Customer Care and Billing used to calculate late payment charges on each Service Agreement Type that has late payment charges.
· The list goes on…
The topics in this section provide background information about a variety of algorithm issues.
Contents
Algorithm Type Versus Algorithm
Minimizing The Impact Of Future Upgrades
You have to differentiate between the type of algorithm and the algorithm itself.
· An Algorithm Type defines the program that is called when an algorithm of this type is executed. It also defines the types of parameters that must be supplied to algorithms of this type.
· An Algorithm references an Algorithm Type. It also defines the value of each parameter. It is the algorithm that is referenced on the various control tables.
Refer to How to Add A New Algorithm for an example that will further clarify the difference between an algorithm and an algorithm type.
Before you can add a new algorithm, you must determine if you can use one of the sample algorithm types supplied with the system. Refer to List of Algorithm Types for a complete list of algorithm types.
If you can use one of the sample algorithm types, simply add the algorithm and then reference it on the respective control table. Refer to Setting Up Algorithms for how to do this.
If you have to add a new algorithm type, you may have to involve a programmer. Let’s use an example to help clarify what you can do versus what a programmer must do. Assume that you require an additional geographic type validation algorithm. To create your own algorithm type you must:
· Write a new program to validate geographic type in the appropriate manner. Alternatively, you may configure a plug-in script to implement the validation rules. The advantage of the latter is that it does not require programming. Refer to plug-in script for more information.
· Create an Algorithm Type called Our Geographic Format (or something appropriate). On this algorithm type, you’d define the name of the program (or the plug-in script) that performs the function. You’d also define the various parameters required by this type of algorithm.
· After creating the new Algorithm Type, you can reference it on an Algorithm.
· And finally, you’d reference the new Algorithm on the Geographic Type that requires this validation.
The system has been designed to use algorithms so an implementation can introduce their own logic in a way that's 100% upgradeable (without the need to retrofit logic). The following points describe strong recommendations about how to construct new algorithm type programs so that you won't have to make program changes during future upgrades:
· Do not alter an algorithm type's hard parameters. For example, you might be tempted to redefine or initialize parameters defined in an algorithm type's linkage section. Do not do this.
· Follow the naming conventions for the new algorithm type code and your source code, i.e., both the source code and the algorithm type should be prefixed with "CM". The reason for this naming convention is to make it impossible for a new, base-package algorithm type from overwriting your source code or algorithm type meta-data (we will never develop a program or introduce meta-data beginning with CM).
· Avoid using inline SQL to perform insert/update/delete. Rather, invoke the base-package's object routines or common routines.
· Avoid using base messages (outside of common messages, i.e., those with a message number < 1000) as we may deprecate or change these messages in future releases. The most common problem is caused when an implementation clones a base package algorithm type program because they need to change a few lines of logic. Technically, to be 100% upgradeable, you should add new messages in the "90000" or greater category (i.e., the category reserved for implementation-specific messages) for every message in your new program even though these messages may be duplicates of those in the base package.
The system is supplied with samples of every type of algorithm used by the system. If you need to introduce a new type of algorithm, open Admin Menu, Algorithm Type.
Refer to The Big Picture Of Algorithms for more information.
Important! If you introduce a new algorithm type, carefully consider its naming convention. Refer to System Data Naming Convention for more information.
Description of Page
Enter an easily recognizable Algorithm Type and Description.
Owner indicates if this algorithm type is owned by the base package or by your implementation (Customer Modification). The system sets the owner to Customer Modification when you add an algorithm type. This information is display-only.
Enter a Long Description that describes, in detail, what algorithms of this type do.
Use Algorithm Entity to define where algorithms of this type can be "plugged in".
Note. The values for this field are customizable using the lookup table. This field name is ALG_ENTITY_FLG.
Use Program Type to define if the algorithm's program is written in COBOL, Java or Plug-In Script.
COBOL Programs. COBOL programs are only supported as part of Oracle Utilities Customer Care and Billing.
Plug-In Scripts. Plug-in scripts are only supported for Java-enabled plug-in spots. Refer to the Plug-In Scripts section for more information.
Use Program Name to define the program to be invoked when algorithms of this type are executed:
· If the Program Type is COBOL, enter the name of the COBOL program.
· If the Program Type is Java, enter the Java class name.
· If the Program Type is Plug-In Script, enter the plug-in script name. Only plug-in scripts defined for the algorithm entity may be used.
View the source. If the program is shipped with the base package, you can use the adjacent button to display the source code of this program in the source viewer or Java docs viewer. Please note that plug-in scripts are developed by implementations (none are shipped with the base-package).
Use the Parameter Types grid to define the types of parameters that algorithms of this type use. The following fields should be defined for each parameter:
· Use Sequence to define the relative position of the Parameter.
· Use Parameter to describe the verbiage that appears adjacent to the parameter on the Algorithm page.
· Indicate whether the parameter is Required. This indicator is used when parameters are defined on algorithms that reference this algorithm type.
· Owner indicates if the parameter for this algorithm type is owned by the base package or by your implementation (Customer Modification). The system sets the owner to Customer Modification when you add an algorithm type with parameters. This information is display-only.
Where Used
An Algorithm references an Algorithm Type. Refer to Setting Up Algorithms for more information.
List of available algorithms types. The algorithm types available to use with the product may be viewed in the application viewer's algorithm viewer. In addition if your implementation adds algorithm types or adds algorithms to reference existing algorithm types, you may regenerate the application viewer to see your additions reflected there.
If you need to introduce a new algorithm, open Admin Menu, Algorithm. Refer to The Big Picture Of Algorithms for more information.
Description of Page
Enter an easily recognizable Algorithm Code and Description of the algorithm. Ownerindicates if this algorithm is owned by the base package or by your implementation (Customer Modification).
Important! If you introduce a new algorithm, carefully consider its naming convention. Refer to System Data Naming Convention for more information.
Reference the Algorithm Type associated with this algorithm. This field is not modifiable if there are parameters linked to the algorithm (defined in the following collection).
Refer to Algorithm Type Versus Algorithm for more information about how an algorithm type controls the type of parameters associated with an algorithm.
Define the Value of each Parameter supplied to the algorithm in the Effective-Dated scroll. Note that the Algorithm Type controls the number and type of parameters.
Where Used
Every control table that controls component-driven functions references one or more algorithms. Refer to the description of Algorithm Entity under Setting Up Algorithm Types for a list of all such control tables.