Function Call

From PresenceWiki
Jump to: navigation, search

What are Function Calls?

A function call within Presence is an instruction to the Task engine to execute a piece of discreet logic based on parameters and to return a result. The function is executed when the Task runs and the calling syntax is replaced by that result.

Function calls use the following syntax:

&functionName{"param1","param2",...}

Specifically, an ampersand (&) followed immediately by the function reference name, followed by one or more comma-separated parameters enclosed in curly brackets - { }

Mechanics of Function Calls

Presence has a concept of dynamic text. Nodes generally accept dynamic text anywhere that an input value is required - for example, the SQL statement text in an SQL node, the Variable Value text in a Set Variable Node, etc. Dynamic text can include Variable references, Data Table Column References and Function calls. When Presence encounters dynamic text it is evaluated at runtime and replaced with the correct result.

When a Function Call is encountered (recognised by the execution engine as an ampersand followed by a keyword followed by curly brackets) a lookup is performed to find the Java class that matches the function keyword. A new instance of that class is created, and the parameters are sent to it, then a method is called to get the text result. The engine then replaces the original function call with the resulting text.

To see this in action, launch the Function Tester from the Administration console. This is the 5th icon from the right (function call test pad).

Try the following example:

"A random number between 0 and 50 is &random{50}"

and press "Parse".

The result should be self-explanatory.

Managing Functions

Functions can be imported, exported or created through the Administration console Function Manager tool. This is the 4th icon from the right at the top of the screen ("fn").

Sometimes you may need to import a function that has been written by the Presence development team or a third party. To do this, right click on the list of available functions (the left panel) and choose "Import function" from the pop-up menu. You will be asked to select a file with the extension "pfa" - this stands for Presence Function Archive. It includes instructions to Presence on how the function should be called (the function keyword and expected parameter) and usually the Java class that should be invoked.

Testing functions

To test functions outside a Task environment please use the Function Test Console.

Creating new Functions (technical)

We have tried to make writing your own functions for Presence as easy as possible, provided you are familiar with programming in Java. Here are the steps you need to take:

Create a Java class that implements the abstract class com.internationalpresence.exec.FunctionAbstract

Implement the following abstract method:

public abstract Object getResult() throws FunctionCallException;

To obtain the parameters that were passed to the Function use the following methods:

String -> public String getNextStringParameter (boolean required) throws InvalidFunctionCallException Double -> public Double getNextDoubleParameter (boolean required) throws InvalidFunctionCallException Integer -> public Integer getNextIntegerParameter (boolean required) throws InvalidFunctionCallException

Etc.

Note the "required" boolean - if set to true this will cause the method to throw an InvalidFunctionCallException if the parameter has not been set. Otherwise the method will return a null object.

Here is an example of a very simple Function which accepts someone's name as a parameter and returns a message saying "hello".

package myfunctions;
import com.internationalpresence.exec.FunctionAbstract;
public class SayHelloFunction extends FunctionAbstract implements PresenceFunction {
   
   public Object getResult() throws FunctionCallException {
       String name = getNextStringParameter(true);
       return "Hello "+name;
   }
}

As you can see this is quite simple and requires very little additional coding to integrate with Presence.

After creating the class you must export it as a Jar file and import it into Presence using the Presence Jar Manager. Next, right click on the list of functions in the function manager and choose "Register new function" from the pop-up menu. You will then be presented with the New Function Wizard which will ask you for the class name (e.g. myfunctions.SayHelloFunction above), a usage description, the group that the function should be placed in, and the parameters.

If you would like any assistance with these steps, please contact us and we will be delighted to help.

Commonly used Functions

Presence ships with many pre-defined Functions which should provide you with most of the functionality you need for your Tasks.

To view the full list of functions, use the Function manager. Selecting a function from the list on the left will display the description (and usage information) in the main window.

The most commonly used functions perform text formatting, date formatting and numeric calculations.

See also: