Fluent Function · Transact Services Guide (TSG)

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

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

Function API

Fluent Functions all 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 Param

The param FuncParam object provides the set of inputs for the function's execution. All the function inputs are immutable with the exception of the appDoc XML Document. Making changes to the XML Document will be persisted after all the functions have been executed. If a function throws an exception however changes to the XML Document will not be 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&lt;ValidationError> errors = new ArrayList&lt;>()
  
    // 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:

continueProcessing: The flag specifies whether any functions to be executed after this function should be run. This provides your function the ability to abort further process an return any validation errors immediately back to the user. Please note any application transaction changes will be persisted to the database.
data: The data field provides a map of result values which will be returned to the Maestro form as a JSON object under the attribute name: data
includeFormData: The flag specifies whether the XML form data Document should be returned to the Maestro form as a JSON attribute under the name: formData
errors: The errors field provides a array of ValidationError values to be returned to the Maestro form as JSON array under the attribute name: errors. Generally if a Fluent Function returns errors, any application transaction changes will still be persisted to the database. The exception however is if the user performs a "User Submit" operation, in this case if a function returns any errors the application transaction will be rolled back, and any changes to the application will be reverted. This to ensure the application remains in a consistent state.
redirectUrl: The redirectUrl field specifies that the URL that the users browser should be redirected. This value is returned to the Maestro form as a JSON attribute with the name: redirectUrl

Function Triggers

Fluent Functions can be triggered on a variety of form events including:

Trigger Type	Description
Form Open	Called when new form transaction is created, immediately before it is rendered to the browser. This event trigger is initiated by the Journey Manager server.
Form Resume	Called when a saved form transaction is resumed, immediately before it is rendered to the browser. This event trigger is initiated by the Journey Manager server.
Form Update	Called when the form makes an background update operation. This event trigger is initiated by the Maestro Form in the browser.
Form Ineligible	Called when the form determines the user is ineligible to complete the application. This event trigger is initiated by the Maestro Form business rule scripts in the browser after determining the user is not eligible to complete the application.
Form Function	Called by Maestro Form business rule scripts generally to get dynamic data from the server and perform any transaction updates. This event trigger is initiated by the Maestro Form business rule scripts in the browser.
User Save	Called when the user explicitly saves and closes the form. This event trigger is initiated by the user of the Maestro Form in the browser.
User Submit	Called when the user explicitly submits a completed form application. This event trigger is initiated by the user of the Maestro Form in the browser.
User Cancel	Called when the user explicitly cancels and closes a form application. This event trigger is initiated by the user of the Maestro Form in the browser.

To configure Form Function Triggers you can do this either 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

The Journey Manager handles Fluent Function errors and exceptions as listed below.

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

Function Template

This section shows Groovy script function template.

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 Template

This section shows Groovy script unit test template.

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
    }
}