Skip to main content

Version: 22.04

Fluent Function

Fluent Functions provide server side function event handlers for a variety of form event triggers.

The Fluent Function programming interface is the same across a variety of function triggers enabling you to re-use function code in a variety of contexts. For example, you could define a single function to do both data pre-fill when a form is first opened and also when a saved form is resumed.

Function API

All Fluent Functions have the same programming interface taking a FuncParam parameter and returning a FormFuncResult object.

class FluentFunction {

FuncResult invoke(FuncParam param) {

// Business logic...

FormFuncResult result = new FormFuncResult()

return result
}
}

Function Parameters

param is a FuncParam object that provides the set of inputs for the function's execution. All the function inputs are immutable with the exception of the appDoc XML Document. Changes to the XML Document are persisted after all the functions have been executed. However, if a function throws an exception, changes to the XML Document are not stored.

class FuncParam {

// The function trigger
final String trigger

// The mutable XML application document
final Document appDoc

// The request parameters
final Map<string object> params

// The HTTP request
final HttpServletRequest request

// The service definition
final SvcDef svcDef

// The transaction
final Txn txn

// The user
final User user
}

Function Result

The FormFuncResult return object provides the output information used by the system to implement its behavior.

class FormFuncResult {

// Specify whether to continue processing remaining functions
boolean continueProcessing = true

// Specify any result data
final Map<string object> data = new TreeMap()

// Include XML formData in response
boolean includeFormData = false

// Specify validation errors to be returned to the form
final List<ValidationError> errors = new ArrayList<>()

// Redirect the end user to another location (optional)
String redirectUrl
}

Each of the result object fields provide specific instructions for the system behavior. These include:

FieldDescription
continueProcessingboolean
Whether to run any functions that were to be executed after this function.
This provides your function with the ability to abort further processing and return any validation errors immediately back to the user. Any application transaction changes are persisted to the database.
dataMap<string object>
A map of result values returned to the Maestro form.
Results are returned as a JSON object attribute called data.
includeFormDataboolean
Whether the form XML data Document should be returned to the Maestro form
Form XML data is returned as a JSON attribute called formData.
errorsList<ValidationError>
An array of ValidationError values to be returned to the Maestro form as a JSON array attribute called errors.
Generally, if a Fluent Function returns errors, any application transaction changes are still persisted to the database. However, an exception is if the user performs a User Submit operation, in which case if a function returns any errors the application transaction will be rolled back, and changes to the application are reverted. This ensures the application remains in a consistent state.
redirectUrlThe URL that the user's browser should be redirected to.
This value is returned to the Maestro form as a JSON attribute called redirectUrl.

Function Triggers

Fluent Functions can be triggered on a variety of form events.

Trigger TypeDescription
Form OpenCalled when new form transaction is created, immediately before it is rendered to the browser.
Initiated by the Journey Manager server.
Form ResumeCalled when a saved form transaction is resumed, immediately before it is rendered to the browser.
Initiated by the Journey Manager server.
Form UpdateCalled when the form makes an background update operation.
Initiated by the Maestro Form in the browser.
Form IneligibleCalled when the form determines the user is ineligible to complete the application.
Initiated by the Maestro Form business rule scripts in the browser after determining the user is not eligible to complete the application.
Form FunctionCalled by Maestro Form business rule scripts, generally to get dynamic data from the server and perform any transaction updates.
Initiated by the Maestro Form business rule scripts in the browser.
User SaveCalled when the user explicitly saves and closes the form.
Initiated by the user of the Maestro Form in the browser.
User SubmitCalled when the user explicitly submits a completed form application.
Initiated by the user of the Maestro Form in the browser.
User CancelCalled when the user explicitly cancels and closes a form application.
Initiated by the user of the Maestro Form in the browser.

You can configure Form Function Triggers in the Management Console via the Form Version Functions tab.

Form Function Configuration

Form Functions can also be configured by editing an Application Package form-def.json file in a developers workspace.

{
"name": "Credit Card Application",
...
"formVersions": [{
"versionNumber": "1.0",
...
"formFunctions": [
{
"trigger": "Form Open"
"name": "Data Loader",
"version": "1.0.1",
"sequence": 1
},
{
"trigger": "Background Delivery"
"name": "Application Delivery",
"version": "1.0.0",
"sequence": 1
}
]
...
]
}

Exception Handling

Journey Manager handles Fluent Function errors and exceptions for the various trigger types as follows.

Trigger TypeException Handling
Form Open
Form Resume
Functions throwing an exception cause the form rendering to be aborted and an error page to be displayed to the user.
The error is logged with the Groovy Service Log record.
Form FunctionFunctions throwing an exception cause HTTP 500 response to be returned to the browser with the error key stdErrs.systemError.
The root cause exception is logged to the Error Log and associated Groovy Service Log.
Form Update
Form Ineligible
User Save
User Submit
User Cancel
Functions throwing an exception cause HTTP 500 response to be returned to the browser with the error key stdErrs.systemError.
The root cause exception is logged to the Error Log and associated Groovy Service Log.
The database transaction associated with this command is rolled back and any application updates are reverted.

Templates

Fluent Function

import com.avoka.tm.func.*
import com.avoka.tm.svc.*
import com.avoka.tm.util.*
import com.avoka.tm.vo.*
import javax.servlet.http.*

class FluentFunction {

// Injected at runtime
public Logger logger

/*
* Perform Fluent Function call.
*
* returns: FuncResult
*/
FuncResult invoke(FuncParam param) {

// TODO: replace business logic

FormFuncResult result = new FormFuncResult()

return result
}
}

Unit Test

import com.avoka.tm.func.*
import com.avoka.tm.svc.*
import com.avoka.tm.test.*
import com.avoka.tm.util.*
import com.avoka.tm.vo.*
import org.junit.*

class UnitTest extends AbstractJUnitTest {

// Injected at runtime
public static Logger logger

/*
* Perform service unit test
*
* throws exception if unit test fails
*/
@Test
void testFunction() throws Exception {

FuncParam funcParam = new MockVoBuilder()
.createFuncParam(FuncParam.TRIGGER_FORM_UPDATE, Txn.FORM_SAVED, svcDef, testParams);

FormFuncResult result = (FormFuncResult) new ServiceInvoker(svcDef)
.setLogger(logger)
.invoke("funcParam", funcParam)

logger.info result

assert result != null
}
}