Migrate a Custom Function Handler to a Custom Function Extension

Migrate a Custom Function Handler to a Custom Function Extension

Custom Functions Handlers (previously known as simply “custom functions”) have been deprecated in version 10.2 of Oracle Policy Automation in favour of Custom Function Extensions, a strongly typed method of defining custom functions that is more powerful and allows for easier reuse across projects.

Some comparisons are given below:

 

  Custom Function Handlers Custom Function Extensions
Invocation

Invoked using “CallCustomFunction”, parameters must be attributes with public names; for example,

Result = CallCustomFunction(“Foo”, “p1,p2,p3”)

Invoked just like a regular function; for example,

Result = Foo(parameter1, parameter2, etc)

Context A rule that uses CallCustomFunction needs “known” conditions on all dependent attributes as a hint to the determinations engine which attributes should cause the rule to be re-evaluated if they change. This typically requires the function to be placed in a table rule in Word, and also precludes its use in Excel. No special operators are required, the custom function can be used anywhere a built-in function can.
Validation Rule documents that call the custom function are not validated to ensure they use the function correctly. Name of the function, return type and parameter types are all strongly typed. These are all validated when compiling a rule document that calls the function.
Decision Reports Does not participate in decision reports, although the “known” clauses mentioned above can simulate this. By default all parameters appear in decision reports, more complex relevance can also be implemented.
Unknown and Uncertain Custom function implementation must deal with possible unknown and uncertain values. Unknown/uncertain is automatically handled, although this can be overridden.
Temporal Reasoning Custom function implementation must deal with change points or the calling application (and rules) must avoid using them. Custom function automatically supports change points. Custom behaviour can also be implemented.
Deployment Java/.NET Implementation can be packaged with compiled rulebase but this requires manual configuration in each project that uses it. Java/.NET implementation and function definition is packaged together and can be freely copied between projects if desired.

 

The steps to migrate a custom function handler to a custom function extension are as follows:

  1. Create the definition of the functions and the argument they take inside a new extension.xml file.
  2. Rewrite the custom function class to extend the CustomFunction class instead of implementing the CustomFunctionHandler interface. The main code changes to note are:
    1. If the old class handled multiple custom functions, you will probably want to create a separate class for each function.
    2. Although the CustomFunction class has more methods, most of them have default implementations other than evaluate.
    3. The evaluate has a different signature and slightly different semantics, most notably the arguments passed to the function are no longer the names of attributes to look up, they are now the values passed to the function. Looking up attributes is usually not necessary.
    4. Custom function handlers need to deal with the possibility of unknown and uncertain values of attributes, but with a custom function extension, this is not necessary unless the requireKnownParameters method has been overridden to return false.
  3. Package the compiled DLL or JAR files with the extension.xml file as an extension and copy it into the rulebase project’s “extensions” folder.
  4. Rewrite rules that call the custom function; usually this will mean:
    1. Instead of invoking CallCustomFunction, with a pair of quoted strings, the function can be called by name and the arguments directly inserted into the function call.
    2. “known” conditions used with CallCustomFunction, can usually be removed. This often means the function call no longer needs to be in a table rule (although of course that is still permissible).
See also:

Write a Custom Function extension

Custom Function extensions