Package com.avoka.fc.core.service.submission

Class DeliveryCheckpointService

  • public class DeliveryCheckpointService
extends CayenneService
    Provides service for using submission delivery process checkpoints for creating robust multi-step delivery processes.

    Delivery checkpoints are used by the SubmissionDeliveryControllerService to determine whether a multi-step delivery processes have been completed or needs to be retried.

    Always ensure you specify your checkpoints as having been completed if the checkpointed delivery step has been successful.

    When attempting to delivery a form submission the SubmissionDeliveryController will only consider a submission to be completed if ALL registered Checkpoints have been completed. Otherwise the controller will consider this to be a delivery error and will record it as a submission delivery error.

    When using delivery checkpoint you must ensure your Delivery Groovy Script does not throw an exception outside of a delivery checkpoint block, otherwise the SubmissionDeliveryController will rollback the transaction and changes made including registered delivery checkpoints or errors will be lost.

    Multi-Step Delivery Example

    The Groovy script delivery process below is performing 3 separate delivery steps to integrate with external systems.

    1. Salesforce - Add a web lead in Salesforce
    2. Database - Update web accounts table
    3. Email - Send email lead to sales

    Before performing an integration step the deliveryCheckpoint service is queried to see whether this step has already been completed, in the case of performing a delivery retry. Once a step has been successfully completed then a delivery checkpoint is created. 

     if (deliveryCheckpoint.doCheckpoint("Salesforce", "Add a web lead in Salesforce")) {
    try {
       // TODO: provide your custom delivery code
       // ..

       deliveryCheckpoint.completedCheckpoint("Salesforce")

    } catch (Throwable e) {
       deliveryCheckpoint.errorCheckpoint("Salesforce", e)
    }
 }

 if (deliveryCheckpoint.doCheckpoint("Database", "Update web accounts table")) {
    try {
       // TODO: provide your custom delivery code
       // ..

       deliveryCheckpoint.completedCheckpoint("Database")

    } catch (Throwable e) {
       deliveryCheckpoint.errorCheckpoint("Database", e)
    }
 }

 if (deliveryCheckpoint.doCheckpoint("Email", "Send email lead to sales")) {
    try {
       // TODO: provide your custom delivery code
       // ..

       deliveryCheckpoint.completedCheckpoint("Email")

    } catch (Throwable e) {
       deliveryCheckpoint.errorCheckpoint("Email", e)
    }
 }

    Important Note

    Do not to throw unhandled exceptions outside of delivery checkpoint blocks, otherwise any checkpoint changes will be lost when the transaction is rolled back by the SubmissionDeliveryController. Make sure you catch any errors in your checkpoint blocks and log the error with the DeliveryCheckpointService.
    Since:
    3.5.0
    See Also:
    GroovyDeliveryProcessService

    • Constructor Detail

      • DeliveryCheckpointService

        public DeliveryCheckpointService​(Submission submission,
                                 String deliveryServiceName)
        Create a service based on the given submission and delivery service name.
        Parameters:
        submission - the submission (required)
        deliveryServiceName - the name of the delivery service (required)

    • Method Detail

      • doCheckpoint

        public boolean doCheckpoint​(String name)
        Return true if the checkpoint should be performed, either hasn't been registered or an error has occurred previously.

        If the checkpoint has not already been registered this method will create a new checkpoint.

        Parameters:
        name - the name of the checkpoint to check, and register if it doesn't exist (required)
        Returns:
        if the checkpoint needs to be performed or false if already completed
        Since:
        4.2.0

      • doCheckpoint

        public boolean doCheckpoint​(String name,
                            String description)
        Return true if the checkpoint should be performed, either hasn't been registered or an error has occurred previously.

        If the checkpoint has not already been registered this method will create a new checkpoint.

        Parameters:
        name - the name of the checkpoint to check, and register if it doesn't exist (required)
        description - the checkpoint description (optional)
        Returns:
        if the checkpoint needs to be performed or false if already completed
        Since:
        4.2.0

      • isCompleted

        public boolean isCompleted​(String name)
        Return whether a 'Completed' checkpoint with the specified name already exists for the submission.
        Parameters:
        name - the checkpoint name (required)
        Returns:
        true if the 'Completed' checkpoint already exists

      • registerCheckpoint

        public boolean registerCheckpoint​(String name)
        Register a new delivery checkpoint with the given name, if it does not already exist.
        Parameters:
        name - the delivery checkpoint name (required)
        Returns:
        true if the new delivery checkpoint was registered or false if the checkpoint was already present

      • registerCheckpoint

        public boolean registerCheckpoint​(String name,
                                  String description)
        Register a new delivery checkpoint with the given name and description, if it does not already exist.
        Parameters:
        name - the delivery checkpoint name (required)
        description - the delivery checkpoint description (optional)
        Returns:
        true if the new delivery checkpoint was registered or false if the checkpoint was already present

      • completedCheckpoint

        public boolean completedCheckpoint​(String name)
        Add a Completed the delivery checkpoint with the given name, if it does not already exists.
        Parameters:
        name - the checkpoint name (required)
        Returns:
        true if the new completed delivery checkpoint was added or false if the checkpoint was already present

      • completedCheckpoint

        public boolean completedCheckpoint​(String name,
                                   String description)
        Add a Completed the delivery checkpoint with the given name, if it does not already exists.
        Parameters:
        name - the checkpoint name (required)
        description - the delivery checkpoint description (optional)
        Returns:
        true if the new completed delivery checkpoint was added or false if the checkpoint was already present

      • errorCheckpoint

        public void errorCheckpoint​(String name,
                            Object error)
        Add a Error the delivery checkpoint with the given name, if it does not already exists. If the passed in error object is an Throwable error it will be logged to the Error Log and associated with the Submission.
        Parameters:
        name - the checkpoint name (required)
        error - message the delivery checkpoint error message (optional)

      • clearAllCheckpoints

        public void clearAllCheckpoints()
        Deletes all existing delivery checkpoints for the configured submission. This method performs a database commit.

      • addCheckpoint

        protected boolean addCheckpoint​(String status,
                                String name,
                                String description)
        Add a delivery checkpoint with the given status, name and description.
        Parameters:
        status - the checkpoint status (required)
        name - the checkpoint name (required)
        description - the checkpoint description (optional)
        Returns:
        true if the checkpoint was added or false, if the named checkpoint already existed