Delivery Function

Delivery Functions are used to deliver user entered form data when a transaction is submitted. This form data includes the submitted form XML, the PDF receipt document and many also include user uploaded file attachments. Please note delivery functions can also be used to delivery data from user abandoned transactions if configured.

Function Parameters

Parameter	Description	Optional
param	the function parameter, see FuncParam	no

Delivery Function Processing

Delivery Functions have special execution facilities provided by Journey Manager to ensure they can be re-run if errors occur. Before a delivery function is run it is registered with the transaction and its execution is tracked. If the function completes successfully its invocation status will be marked as 'Completed'. However, if a function fails its invocation status will be marked as 'Error'. This transaction delivery function can then be automatically retried by the background Transaction Processor job.

Delivery Functions can be invoked when a form is submitted by configuring them to run on the "User Submit" form trigger. This facility enables Straight Through Processing (STP) or real-time delivery. If a Delivery Function fails when the user submits the form due to a back-end error or some schedule maintenance then the function can be automatically re-run by the Transaction Processor job in the next few minutes.

Please note when configuring delivery functions to run on the user thread they should complete relatively quickly so they do not impact the user experience. A reasonable maximum period of time for delivery is around 10-30 seconds, after this the user will probably be confused by the application not responding. When making remote HTTP calls please ensure short connection timeouts are set, so the function does not block for long periods of time on these calls. The default executionTimeout configuration for Delivery Functions is 30 seconds after this period of time the execution of the function will be aborted.

Delivery functions can also be configured on run in background delivery mode only by configuring the "Background Delivery" form trigger.

Please note when a Delivery Function is executing when the user submits a form the PDF receipt document will not be available yet. Generally PDF receipts are generated using a background process and generally take a couple of minutes to generate after a form has been submitted. If you need both real-time delivery for STP and the delivery of the PDF receipt to another system, please configure 2 separate Delivery Functions one to be executed on the "User Submit" trigger and another function configured to execute on the "Background Delivery" trigger.

If a delivery function determines that it can't complete at this point in time it should return a DeliveryFuncResult result with the delivery status of 'In Progress'. This delivery function will then be executed again in the future when the configure delay period has been reached.

The DeliveryFunc result can be used to specify the replay period minutes before the function is retried and can also specify the maximum number of Error retry attempts.

When all a transactions delivery functions have completed successfully the Transaction is finished and its PII data will be configured to be purged at a future point in time. The default PII data retention settings is 7 days, this provides some time to enable re-delivery of transaction PII data if a downstream processing error has occurred.

Error Handling

If a Delivery Function throws an exception it will be caught and the transaction delivery function will be marked as being in an 'Error' state. When delivery functions are executed in the background by the Transaction Processor they are executed in their own database transaction and any changes they make in this transaction will be rolled back. However when delivery functions are executed by the user when the submit the form they will execute in the users database transaction, and any changes they make will be committed to the database.

We recommend developer use try / catch blocks in their Delivery Function Groovy code to control their error handling behavior and return an DeliveryFuncResult object with the 'Error' status specified and what the function retry semantics should be.

The Delivery Function can be configured with the maxDeliveryAttempts service parameter to specify the automatic retry attempts, and also the retryDelayMins to specify when the function should be retried again. Please note the maxDeliveryAttempts configuration parameter applies to transaction delivery functions in an 'Error' and 'In Progress' state, once the maximum number of attempts has been reached the system will not continue to retry the function.

Function Template

This section shows Groovy script function template.

import com.avoka.tm.func.*
import com.avoka.tm.util.*
import com.avoka.tm.vo.*

class DeliveryFunction {

    // Injected at runtime 
    public Logger logger

    /*
     * Perform Delivery Function call.
     *
     * returns: DeliveryFuncResult
     */
    DeliveryFuncResult invoke(FuncParam param) {

        // TODO: add delivery code

        return new DeliveryFuncResultBuilder()
            .setStatusCompleted()
            .build();
    }
}

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_BACKGROUND_DELIVERY, Txn.FORM_COMPLETED, svcDef, testParams);

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

        logger.info result

        assert result != null
    }
}