Package de.xima.fc.interfaces.workflow.triggers

Interface ITriggerHandler<TData>

Type Parameters:
TData - Type of the properties model for the trigger. Use JSONObject if you want to get the raw data and possibly perform serialization / deserialization yourself. See IElementHandler.getDataModelClass().
All Superinterfaces:
ICustomParametersUpdateable, IElementHandler<TData,WorkflowTrigger>, IResourceBundleLocator, ITriggerDataDescriptor, IWorkflowElementTypeProviding, IWorkflowTriggerTypeProviding
All Known Subinterfaces:
IBaseTrigger<TData>, IBeanValidatingTrigger<TData>, IBuiltinTriggerType<TData>, IDefaultClientHandlerTrigger<TData>, IOfficialHelpPageTrigger<TData>, IPluginTriggerHandler<TData>, ISemverUpdatingTrigger<TData>, ISingleBaseBuiltinTriggerPrototype<TData>, ISingleBaseTriggerPrototype<TData>, ISingleBuiltinTriggerPrototype<TData>, ISingleTriggerPrototype<TData>, ISpecificTriggerListener<TData>
All Known Implementing Classes:
APluginTriggerHandler, FcCatchErrorHandler, FcDoiVerifiedHandler, FcFormSubmitButtonHandler, FcInvitationErrorHandler, FcInvitationSentHandler, FcManualHandler, FcQualifiedFormSubmitButtonHandler, FcStateTimerHandler, FcTimePointHandler
public interface ITriggerHandler<TData> extends IElementHandler<TData,WorkflowTrigger>, IWorkflowTriggerTypeProviding, ITriggerDataDescriptor
All trigger handlers must be thread-safe. Usually you should not have any instance fields in your handler.

Interface for registering workflow triggers. Each workflow trigger has a given type, and a handler needs to be registered for each type. The handler is responsible for processing the trigger during execution, for displaying the trigger during editing, and for validating the trigger.

For plugins, it is strongly recommended that you override IElementHandler.getVersion() and use the version of the plugin instead. You should also override IElementHandler.getResourceBundle(java.util.Locale) and provide a resource bundle for your plugin.

A trigger is responsible for responding to an event and initiating a workflow task. This process works as follows:

  1. The system or a plugin creates an instance of IWorkflowEventData, and passes it to the workflow engine.
  2. The workflow engine locates all WorkflowTasks whose trigger reacts to the event data. This is done in the following steps:
    1. A database query is prepared and filled with the basic details of the event. The result is always restricted to the client. Additionally IFormRecordProvidingEvent restricts the result to a certain form record, a IProjectProvidingEvent restricts the result to a certain project.
    2. For each trigger handler known to the system (both built-in and plugins), a call is made to #getFilterCriteriaForEvent. Each handler may restrict the query further, depending on the event data.
    3. The query is executed and a candidate list of matching triggers is retrieved from the database.
    4. For each candidate trigger, a call is made to #isAppliesToEvent. Candidates where this method returns false are discarded. This can be used in cases where no database where clause can be constructed to check whether the event applies. All triggers that pass the check are returned.
  3. All tasks are grouped by their FormRecord, and sorted according to their position in the WorkflowProcess.getTasks() list.
  4. The workflow engine executes each task in order (not in parallel). Before each task is executed, a call is made to isPreconditionSatisfied(ITriggerPreconditionSatisfiedParams). The precondition may have been satisfied when the event was triggered originally, but may have ceased to be satisfied after a previous task was executed.
  5. The result of execution is returned to the system or plugin.
Since:
7.0.0
Author:
XIMA MEDIA GmbH

  • Method Details

    • getFilterCriteriaForEvent

      @Nullable de.xima.cmn.criteria.FilterCriterion getFilterCriteriaForEvent(ITriggerFilterCriteriaForEventParams params)
      Called once with the event data when an event is fired. Each handler may add filter criteria to locate the triggers that match the event data.

      This method must return a non-null value to indicate that the event applies to this type of trigger at all. When this returns null, no triggers of this handler type are considered. The filter criterion returned by this method is used for a query for WorkflowTrigger entities, i.e. all attribute names must be relative to that entity.

      For example, to limit the result to triggers which have a search term with the key customKey set to valueForCustomKey, use: 

       return params.searchTermExists("customKey", valueForCustomKey);
      To create a complex filter, use or / and etc. If you cannot use a database filter to check whether a trigger applies, use always to fetch all triggers for this handler type, and implement isAppliesToEvent to filter the applicable triggers via Java code.

      Basic restrictions such as the trigger type, the form record and project are applied automatically by the system and do not need to be included in the returned filter.

      See the class level documentation ITriggerHandler for more details.

      Parameters:
      params - Parameters with the event data of the event that occurred.
      Returns:
      A filter criterion to restrict the list of matching triggers for this handler type. When null is returned, no triggers of this handler type are considered.
      Throws:
      RuntimeException - Should not throw under normal circumstances. Any exception throws by this method is caught and logged; and no triggers of this type are considered.

    • getLocalizedTypeName

      default String getLocalizedTypeName(Locale locale)
      Finds the localized name of this trigger type. The default implementation uses the key wf.trigger.[TYPE], and looks up the key in the IElementHandler.getResourceBundle(Locale). If it cannot be found there, it looks it up in the built-in resource bundles. If it cannot be found there either, returns #getType().
      Specified by:
      getLocalizedTypeName in interface IElementHandler<TData,WorkflowTrigger>
      Parameters:
      locale - Locale for which the type name should be returned.
      Returns:
      A human-readable name of this trigger type in the given locale.

    • getPropertiesBeanClass

      default Class<? extends ITriggerPropertiesBean<TData>> getPropertiesBeanClass()
      Description copied from interface: IElementHandler
      Returns the class of the bean that should be used when editing the properties of a workflow element. May be null if you do not required any bean or custom logic. When you only wish to access the properties of your IElementHandler.getDataModelClass(), you do have to use a custom bean - the model is available via the expression language variable model. See IElementHandler.getPropertiesViewXhtml() for further details.

      The default returns null, which uses no extra bean. An extra bean may not be required for simple UIs if you only need to access the properties model of the workflow element - see IElementHandler.getPropertiesViewXhtml().

      Specified by:
      getPropertiesBeanClass in interface IElementHandler<TData,WorkflowTrigger>
      Returns:
      The class of the bean to use for editing a workflow node's properties.
      See Also:

    • getTriggerPrototypes

      List<ITriggerPrototypeDescriptor<TData>> getTriggerPrototypes(IGetTriggerPrototypesParams params)
      Returns a list of all trigger prototypes for this node type. Each prototype appears in the drawer panel of the workflow designer. The user can move a trigger prototype via drag & drop into the design area in the center to add the trigger to the current flowchart.

      You should always return all prototypes, irrespective of whether they are allowed to the current user. IElementHandler.isAvailable(IIsAvailableParams) is checked by the engine, and unavailable trigger types are removed automatically.

      Parameters:
      params - Parameters for this method, such as the current locale for localizing the display name of the prototypes.
      Returns:
      A list of all available prototypes. null is treated as an empty list.
      Throws:
      RuntimeException - This method should normally not throw an exception. A runtime exception may be thrown when the node prototypes cannot be created for an unknown reason. When an exception is thrown, no node prototypes are made available for this handler.

    • isAppliesToEvent

      default boolean isAppliesToEvent(ITriggerAppliesToEventParams<TData> params)
      Called once the database query for matching triggers completes successfully. May be used to restrict the list of candidate triggers returned by the database query for matching triggers. This is useful, for example, when the check cannot be expressed as a database query. The tasks of triggers for which this method returns false are not executed.

      See the class level documentation ITriggerHandler for more details.

      Parameters:
      params - The parameters with the event that occurred and a trigger returned by the database query for matching triggers.
      Returns:
      Whether the given trigger applies to the the given event. If not, the task for that trigger is not executed.
      Throws:
      RuntimeException - Should not throw under normal circumstances. Any exception throws by this method is caught and logged; and the trigger is considered not to apply to the event.

    • isPreconditionSatisfied

      default boolean isPreconditionSatisfied(ITriggerPreconditionSatisfiedParams<TData> params)
      Called once the task of a trigger is about to be executed. This method may return false to prevent the task from being executed. When an event triggers multiple tasks, the execution of one task may invalidate the preconditions for a later task, so this method can be used to check whether the precondition is still satisfied.

      See the class level documentation ITriggerHandler for more details.

      Parameters:
      params - The parameters with the task about to be executed.
      Returns:
      true to proceed with the task's execution, false to skip the task's execution.
      Throws:
      RuntimeException - Should not throw under normal circumstances. Any exception throws by this method is caught and logged; and the precondition is considered not be fulfilled.

    • onTaskBegin

      default IOnTaskBeginRetVal onTaskBegin(ITriggerOnTaskBeginParams<TData> params)
      Callback that is invoked just before a task that has a trigger of this type is executed. You may use this callback method to set up the execution context.

      This method should return the data that should be made available via IWorkflowVariableHandler.getTriggerData(String). This data is also available via a placeholder.

      Parameters:
      params - Parameters passed to the callback that contain the trigger data and the execution context.
      Returns:
      Result of the begin callback, see IOnTaskBeginRetVal.
      Throws:
      RuntimeException - Should not throw under normal circumstances. When this method throws an exception, execution of the task is aborted and the task is marked as a failure.

    • onTaskFinish

      default void onTaskFinish(ITriggerOnTaskFinishParams<TData> params)
      Callback that is invoked just after a task that has a trigger of this type was executed. You may use this callback method to clean up the execution context, such as by removing certain variables added by onTaskBegin(ITriggerOnTaskBeginParams).

      In case onTaskBegin(ITriggerOnTaskBeginParams) threw an exception, this is not called.

      Parameters:
      params - Parameters passed to the callback that contain the trigger data and the execution context.
      Throws:
      RuntimeException - Should not throw under normal circumstances. When this method throws an exception, the task is marked as a failure and will cause remaining tasks to be aborted.