Functions allow declarative processing of data without writing custom code. The solution is based on calling a selected function (users can provide their own specific implementations) and passing the result of this function on to, for example, an automated task. In the case of basic mathematical, quotient, textual or logical operations, it is possible to realize simple transformations without writing a line of code.

The functions created should be as general and flexible as possible. This will allow them to be used in more cases. The system allows you to register and use predefined functions both on the server side and on the browser side.

FunctionAPI

All operations related to actions on functions represent FunctionAPI.

Function registration

Registration on the server

The registration of functions available in the system is done at system startup and dynamically for dynamic resources such as plugins. The registration and storage of functions is the responsibility of FunctionRegistry. During registration, all classes marked with the annotation @Functions, are searched first, then methods marked with the annotation @Function are searched in these classes and are registered as functions.

The registered function must:

• return a value basic type

• define 0 or many parameters of a basic type

• be stateless - it should not store state between calls

The following example shows the definition of a simple function that returns the value of a larger number.

@Functions
public class BasicFunctions
{
    @Function
    public Integer maxOf( Integer a, Integer b )
    {
        return Math.max( a, b );
    }
}

You can specify whether the function applies only to the server (can be used only on the server), only to the browser (can be used only in javascript), or both places. The accessibility parameter, which can be set in the annotation @Function. The parameter of type @FunctionAccessibility and can take the following values:

• SERVER -  the function cannot be used in javascript, i.e. for example in actions (it is not shown at all for actions in PWE in the list with selectable functions), while it can be used in other types of components, i.e. executed on the server.
• BROWSER -  the function can be used in javascript, i.e. in actions, for example, while it can be used in other types of components, i.e. executed on the server (it is not shown at all for these components in PWE in the list with selectable functions).
• ALL - the function can be used anywhere. This is the default value of the parameter.

No accessibility parameter set corresponds to the value of ALL.

The following example shows the definition of a function that is available only to server components. The function returns the name of the user based on his login.

@Functions
public class BasicFunctions
{
    @Function( accessibility = FunctionAccessibility.SERVER )
    public String userFullName( String userName )
    {
        User user = userService.getUser( userName );
        if ( user == null )
        {
            return null;
        }
        return user.getFullName();
    }
}

If the function is created for the browser then there must also be a function defined on the server, but its implementation does not have to do anything. It is only to retrieve the name and parameters of the function and display it in the PWE.

Function context

The function context contains the identifier and definition of the currently processed process and task. Retrieving the context is possible only on the server side using the following code.

FunctionContext context = FunctionContext.current(); // statyczne pobranie kontekstu
 
String processId = context.getProcessId(); // process id
String activityId = context.getActivityId(); // task id 
String processDefId = context.getProcessDefId(); // process definition id
String activityDefId = context.getActivityDefId(); // task definition id

Browser-side registration

Using the created function on the browser side (on the task form) requires the programmer to provide its implementation in JavaScript. Such an implementation is used during dynamic calculations on the client's browser side.

In the case of functions with JavaScript implementations, you must additionally indicate by annotation @FunctionsScript where the script that contains the implementations of these functions is located. The absolute path to the resource in classpath should be indicated. A resource stored in src/main/resources/functions/basic-functions.js would be indicated like this:

@Functions
@FunctionsScript("/functions/basic-functions.js")
public class BasicFunctions
{
    ...
}

Functions are registered using the API PW.fn.Functions (short name PW.Functions):

// function "max" which returns an object of type "float" and takes 2 parameters of type "float"
PW.Functions.register("max", "float", ["float", "float"], function(value1, value2){
	return Math.max(value1, value2);
});
 
// function "upper" which returns an object of type "string" and accepts 1 parameters of type "string"
PW.Functions.register("upper", "string", ["string"], function(text){
	return text.toUpperCase();
});

When registering a function, it is necessary to define:

• the name (you can register multiple functions with the same name but they must have different parameter types)
• the type of the returned value
• types of parameters
• implementation of the function

A function registered in this way will be called only for calls with arguments that match the defined types. The possible types are described in Build-in types.

Registration in the plugin

The registration of functions in the plugin is the same as described above, but it should be noted in addition that the plugin provides functions to be registered. To do this, add an entry in the suncode-plugin.xml file:

<functions key="functions" />

This entry will automatically search for all functions defined in the plugin.

Translations of function and parameter descriptions

Functions are translated automatically if function translations created using the internationalization mechanism are available. The rules for creating translation keys are described below.

Subject of translation:

• function description
• parameter names
• parameter descriptions

Translation keys of functions must be created with the following rules:

Example:

For a function defined as follows:

@Function
public boolean isHoliday(LocalDate date) {
	// implementation
}

The translations will be as follows:

function.isHoliday=Checks if the date indicates a holiday
function.isHoliday.param.date.name=Date
function.isHoliday.param.date.desc=Checked date

For an obsolete function defined as follows:

@Function
@Deprecated
public boolean isHoliday(LocalDate date) {
	// implementation
}

Translations will be as follows:

function.isHoliday=Checks if the date indicates a holiday
function.isHoliday.param.date.name=Date
function.isHoliday.param.date.desc=Checked date
function.isHoliday.deprecated.description=This function is obsolete and you should use isHoliday(LocalDate date, Locale locale)

Translation of function overloads

Each function may have multiple overloads that take different parameters. You may need to give different descriptions for these parameters or a different function description. This is possible by adding parameter types separated by an underscore (_) to the function name used in the translation key. The default translation is this without parameter types.

The names of the types are available here: Built-in types

Example:

For a function defined as follows:

@Function
public boolean isHoliday(LocalDate date) {
	// implementation
}
 
@Function
public boolean isHoliday(LocalDate[] dates) {
	// implementation
}
 
@Function
public boolean isHoliday(LocalDate[] dates, boolean all) {
	// implementation
}

The translations will be as follows:

function.isHoliday=Checks if the date indicates a holiday
function.isHoliday.param.date.name=Date
function.isHoliday.param.date.desc=Checked date
 
function.isHoliday_date[]=Checks if all specified dates are public holidays
function.isHoliday_date[].param.dates.name=Dates
function.isHoliday_date[].param.dates.desc=Checked dates
 
function.isHoliday_date[]_boolean=Checks if the specified dates are holidays
function.isHoliday_date[]_boolean.param.dates.name=Dates
function.isHoliday_date[]_boolean.param.dates.desc=Cheched dates
function.isHoliday_date[]_boolean.param.all.name=All
function.isHoliday_date[]_boolean.param.all.desc=Check if you want all dates to be holidays