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. Delivery functions can also be used to deliver data from user abandoned transactions if configured.

Function Parameters

All function parameters are optional unless otherwise indicated.

Parameter	Description
param	FuncParam A function parameter.

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'. A transaction delivery function can be retried automatically 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, the function can be re-run automatically by the Transaction Processor job in the following few minutes.

When configuring delivery functions to run on the user thread, they need to 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 may be confused by the application not responding. When making remote HTTP calls, 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 to run in background delivery mode only by configuring the Background Delivery form trigger.

If 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 usually 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, configure two separate Delivery Functions: one function to be executed on the 'User Submit' trigger, and a second function 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'. The delivery function will be executed again when the configured delay period has been reached.

Use the DeliveryFunc result to specify the delay period (in minutes) before the function is retried and the maximum number of error retry attempts.

When all of the delivery functions for a transaction have completed successfully, the transaction is finished and its PII data are configured to be purged later. The default PII data retention setting 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 is caught and the transaction delivery function is 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, if delivery functions are executed by the user when they submit the form, they execute in the user's database transaction, and any changes they make are committed to the database.

We recommend developers use try...catch blocks in their Delivery Function Groovy code to control their error handling behavior, and return a DeliveryFuncResult object with the 'Error' status specified along with the function retry semantics.

The Delivery Function can be configured with the maxDeliveryAttempts service parameter to specify the automatic retry attempts, and also the retryDelayMins to specify when to retry the function again. The maxDeliveryAttempts configuration parameter applies to transaction delivery functions in an 'Error' or 'In Progress' state. Once the maximum number of attempts has been reached, the system stops retrying the function.

Templates

Delivery Function

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

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