Package de.xima.fc.workflow.mixin

Interface IPluginDoUntilLoopNodeHandler<TData extends BaseDoUntilLoopProps,TState extends IWorkflowLoopDataProviding>

Type Parameters:

TData - Type of the node's properties model, which must extend BaseDoUntilLoopProps. The properties themselves are stored as JSON and serialized to / deserialized from this type automatically. You should make sure this type can be serialized / deserialized via JSON. This means you should only basic field types such as number, booleans, or strings, or nested types. Furthermore, if you wish, you can also use the type JSONObject to skip serialization / deserialization and work with the raw JSON data.

TState - Type of the custom state used during the execution of the loop. If you do not require any state, simply set this type parameter to Object.

All Superinterfaces:

IBaseDoUntilLoopClientHandlerNode<TData>, IBeanValidatingElement<TData,WorkflowNode>, IBeanValidatingNode<TData>, ICustomParametersUpdateable, IElementHandler<TData,WorkflowNode>, IExecutingLikePostTestLoopNode<TData>, IExecutionResultDescriptor, IFCPlugin, IHierarchyValidatingNode<TData>, INamedUiElement, INameProviding, INodeHandler<TData>, IPluginGenericCustomGUI<IPluginWorkflowNodeBean>, IPluginWorkflowNode, IRefinedExecutionResultDescriptor<TData>, IResourceBundleLocator, ISingleBaseDoUntilLoopNodePrototype<TData>, ISingleElementPrototype<TData,WorkflowNode>, ISingleNodePrototype<TData>, ITransferable, IWorkflowElementTypeProviding, IWorkflowNodeFlowAnalyzer<TData>, IWorkflowNodeTypeProviding, Serializable

All Known Implementing Classes:

APluginDoUntilLoopNodeHandler

public interface IPluginDoUntilLoopNodeHandler<TData extends BaseDoUntilLoopProps,TState extends IWorkflowLoopDataProviding>
extends IPluginWorkflowNode, INodeHandler<TData>, IBaseDoUntilLoopClientHandlerNode<TData>, IBeanValidatingNode<TData>, IExecutingLikePostTestLoopNode<TData>, ISingleBaseDoUntilLoopNodePrototype<TData>

Mixin meant for IPluginWorkflowNode plugins that only wish to provide a workflow do until loop that runs a test and executes the loop body for as long as the test holds true (= a do until loop). The INodeHandler offers many methods that are irrelevant for this use case - this mixin implements most methods with the appropriate defaults.

By default, you only need to implement evaluateDoUntilLoopTest() and getName(), as well as getPropertiesViewXhtmlName() for the UI. Make sure that the getName() is unique among all plugins. This name is also used as the getType() of the workflow node.

The XHTML page with the UI for editing the do until loop's property must be placed in the directory getPropertiesViewXhtmlPath(), with the file name getPropertiesViewXhtmlName(). You can also add properties files in getResourceBundlePath() with localized messages for the UI.

Assume the getType() is MyDoUntilLoopPlugin. Then, if you do not override the defaults:

• Add an XHTML file with the custom UI for the do until loop in /src/main/resources/WEB-INF/ui/FILENAME.xhtml. where FILENAME is the value from getPropertiesViewXhtmlName().
• For each language you want to support, add a properties file in /src/main/resources/WEB-INF/properties/i18n_LOCALECODE.properties. The LOCALECODE is en for English, de for German, fr for French etc. These properties are then available in the XHTML page via the variable msg, see IElementHandler.getPropertiesViewXhtml()
• Add an entry in the properties file for the keys MyDoUntilLoopPlugin.name, MyDoUntilLoopPlugin.desc, MyDoUntilLoopPlugin.label to customize the name of the plugin, the description of the plugin, and the name of the workflow do until loop.

You can also override most methods of this mixin to customize the do until loop plugin. The following lists a few common use cases:

To use a localized name or description

Add an entry to your resource bundle. For the name of the plugin as it appears in the backend plugin configuration menu, use getI18nKeyDisplayName(). For the description that also appears in the backend plugin configuration menu, use getI18nKeyDescription(). For the label of the do until loop as it appears in the workflow designer, use getI18nKeyActionLabel().

To provide custom values to other actions inside the do until loop

Override addCurrentValueDescriptorEntries() to describe which data your loop provides; and use params.currentValue() within evaluateDoUntilLoopTest() to provide the data. See also the example from addCurrentValueDescriptorEntries().

To provide custom result values to other actions after the loop has finished

Override addSuccessValueDescriptorEntries() to describe which results your loop provides when it has finished; and use params.normalResult().success() within finishLoop() to provide the data. If you want to accumulate some value from each iteration and make it available, you can use a custom state object that is available during the entire execution of the loop by overriding startLoop(INodeExecutionParams). See also the example from addSuccessValueDescriptorEntries().

To update the properties model for new versions of the plugin

First make sure the MANIFEST.MF of your plugin contains the appropriate version information, see getVersion(). Then, override updateCustomParams(). If you are using the SemVer (semantic version) format (i.e. your version looks like x.y.z), you may want to use the default methods provided by the mixin ISemverUpdating.

To provide pre-configured do until loops to the drawer panel to the left of the workflow designer

Override getNodePrototypes(), optionally adding the list of prototypes (which contains just one item) returned by the super method implementation.

To display the do until loop in a different category in the workflow designer

Override getSubCategory()

To use a custom UI

Create an XHTML page in getPropertiesViewXhtmlPath(); and override getPropertiesViewXhtmlName() with the name of the XHTML page. For example, if you name the XHTML page myCustomUi and do not override the XHTML path, add the file /src/main/resources/WEB-INF/ui/myCustomUi.xhtml. If you need a custom bean as a controller, also override getMainPluginBeanClass(). See getPropertiesViewXhtml() for more details on the XHTML page.

To use more than one bean

Override getUnmanagedBeans(), but make sure to include getMainPluginBeanClass(). The additional beans can be used in XHTML pages, or referenced via Inject.

To customize the serialization / deserialization process of the properties model

Use the JSONField annotation on the fields of your properties model class, and/or override IElementHandler.getFastJsonConverter()

Since:

8.2.0

Author:

XIMA MEDIA GmbH

Field Summary

Fields inherited from interface de.xima.fc.interfaces.workflow.elements.IElementHandler

CURRENT_HANDLER_VERSION

Fields inherited from interface de.xima.fc.plugin.interfaces.IFCPlugin

CONFIG_FILENAME

Fields inherited from interface de.xima.fc.interfaces.INamedUiElement

ATTR_DISPLAY_NAME

Fields inherited from interface de.xima.fc.entities.interfaces.INameProviding

ATTR_NAME, COL_NAME

Method Summary

Modifier and Type	Method	Description
default void	addCurrentValueDescriptorEntries(IValueDescriptorFactory factory, IRecordValueDescriptorBuilder builder)	Optional method to add additional data to be made available to other workflow actions during a loop iteration.
default void	addSuccessValueDescriptorEntries(IValueDescriptorFactory factory, IRecordValueDescriptorBuilder builder)	Optional method to add additional data to be made available to other workflow actions after the loop has finished.
default void	beginRepetition(INodeExecutionParams<TData> params, TState state, int index)	Callback that is invoked at the beginning of each loop iteration.
default void	endRepetition(INodeExecutionParams<TData> params, TState state, int index)	Callback that is invoked at the end of each loop iteration.
boolean	evaluateDoUntilLoopTest(INodeExecutionParams<TData> params, TState state, int index)	Executes the business logic of this do until loop plugin, and returns whether the do until loop is fulfilled.
default INormalCompletionResult	execute(INodeExecutionParams<TData> params)	Evaluates the do until loop test of this plugin, and executes the loop body for as long as the do until loop test holds true.
default String	extractDescription(TData data)	Retrieves the name that will be stored as AWorkflowElement.getDescription().
default String	extractName(TData data)	Retrieves the name that will be stored as AWorkflowElement.getName().
default void	finishLoop(INodeExecutionParams<TData> params, TState state, int totalCount)	Called once at the end after all iterations are done just before the end of the loop's execution.
default IValueDescriptor<?,? extends IValueBuilder<?>>	getAlwaysValueDescriptor(IValueDescriptorFactory factory)	This default implementation returns a void value descriptor.
default IValueDescriptor<?,? extends IValueBuilder<?>>	getCurrentValueDescriptor(IValueDescriptorFactory factory)	Normally you do not need to override this method, override addCurrentValueDescriptorEntries() instead.
default Class<? extends TData>	getDataModelClass()	This default implementation attempts to read the type of the TData parameter via reflection.
default String	getDescription(Locale locale)	The default implementation returns the localized value of the getI18nKeyDescription() in the getResourceBundle(Locale).
default String	getDisplayName(Locale locale)	The default implementation returns the localized value of the getI18nKeyDisplayName() in the getResourceBundle(Locale).
default IUnionValueDescriptor<String>	getErrorValueDescriptor(IValueDescriptorFactory factory)	This default implementation simply returns no error codes.
default String	getI18nKeyActionLabel()
default String	getI18nKeyActionSearchText()
default String	getI18nKeyActionSubLabel()
default String	getI18nKeyActionTitle()
default String	getI18nKeyDescription()
default String	getI18nKeyDisplayName()
default int	getLoopBodyChildIndex()
default IElementCategory	getMainCategory(IGetElementPrototypesParams params)
default Class<? extends INodePropertyPluginBean<TData>>	getMainPluginBeanClass()
String	getName()	Getter for the name of this plugin.
default INodeHandler<TData>	getNodeHandler()
IPluginInitializeData	getPluginInitializeData()
default Class<? extends INodePropertiesBean<TData>>	getPropertiesBeanClass()	Returns the class of the bean that should be used when editing the properties of a workflow element.
default URL	getPropertiesViewXhtml()	This default implementation returns the XHTML page located at getPropertiesViewXhtmlPath()/getPropertiesViewXhtmlName().
String	getPropertiesViewXhtmlName()
default String	getPropertiesViewXhtmlPath()
default String	getPropertyNameCurrentIndex()	Optional method to change the name of the property that can be used to access the current loop iteration index by other actions in the workflow.
default String	getPropertyNameIterationCount()	Optional method to change the name of the property that can be used to access the total number of iterations by other actions in the workflow once the loop has finished.
default WorkflowNode	getPrototypeElement(IGetElementPrototypesParams params)
default IGuiIcon	getPrototypeIcon(IGetElementPrototypesParams params)	This default implementation returns an icon with arrows arranged in a circle, which is the default icon for a while loop plugin.
default String	getPrototypeLabel(IGetElementPrototypesParams params)	This default implementation returns the localized value of the getI18nKeyActionLabel() in the getResourceBundle(Locale).
default String	getPrototypeSearchText(IGetElementPrototypesParams params)	This default implementation returns the localized value of the getI18nKeyActionSearchText() in the getResourceBundle(Locale).
default String	getPrototypeSubLabel(IGetElementPrototypesParams params)	This default implementation returns the localized value of the getI18nKeyActionSubLabel() in the getResourceBundle(Locale).
default String	getPrototypeTitle(IGetElementPrototypesParams params)	This default implementation returns the localized value of the getI18nKeyActionTitle() in the getResourceBundle(Locale).
default ResourceBundle	getResourceBundle(Locale locale)	This default implementation attempts to read the resource bundle from the getResourceBundlePath().
default String	getResourceBundlePath()
default IUnionValueDescriptor<String>	getSoftErrorValueDescriptor(IValueDescriptorFactory factory)	This default implementation simply returns no error codes.
default IElementCategory	getSubCategory(IGetElementPrototypesParams params)	Optional sub category.
default IValueDescriptor<?,? extends IValueBuilder<?>>	getSuccessValueDescriptor(IValueDescriptorFactory factory)	Normally you do not need to override this method, override addSuccessValueDescriptorEntries() instead.
default Set<String>	getSupportedControlTransferTypes()	Returns the set of control transfer types that this node can handle.
default String	getType()	This default implementation simply returns the getName() of the plugin as the type.
default Iterable<Class<? extends IPluginWorkflowNodeBean>>	getUnmanagedBeans()	This must return a list of backing bean classes that control the user interface and are required by the XHTML Facelet view.
default String	getVersion()	Instead of the FORMCYCLE version, this default implementation returns the current version of this plugin.
default boolean	isCreateProtocolEntryAfterExecution(ICreateProtocolEntryAfterExecutionParams params)	Controls whether a protocol entry is created after the node was executed.
default TState	startLoop(INodeExecutionParams<TData> params)	Called once at the beginning before the loop iterations are started.

Methods inherited from interface de.xima.fc.workflow.mixin.IBaseDoUntilLoopClientHandlerNode

getCascadingStyleSheet, getDoUntilLoopOptions, getJavaScript, isAlwaysCompletesAbruptly

Methods inherited from interface de.xima.fc.interfaces.workflow.mixin.IBeanValidatingElement

getValidationGroups

Methods inherited from interface de.xima.fc.interfaces.workflow.mixin.IBeanValidatingNode

validateLocal

Methods inherited from interface de.xima.fc.interfaces.workflow.ICustomParametersUpdateable

updateCustomParams

Methods inherited from interface de.xima.fc.interfaces.workflow.elements.IElementHandler

extractSearchTerms, getCascadingStyleSheet, getDisplayLabel, getElementSummaryModel, getElementSummaryXhtml, getFastJsonConverter, getFilterCriteriaForEntities, getHelpPageLocation, getJavaScript, isAvailable, isHasUserVisibleName, readEntityReferences, readPlaceholders, validateGlobal, writeEntityReferences, writePlaceholders

Methods inherited from interface de.xima.fc.interfaces.workflow.mixin.IExecutingLikePostTestLoopNode

createFlowGraph

Methods inherited from interface de.xima.fc.interfaces.workflow.execution.IExecutionResultDescriptor

getAttachmentValueDescriptor, getCurrentAttachmentValueDescriptor, getCurrentFileValueDescriptor, getFileValueDescriptor

Methods inherited from interface de.xima.fc.plugin.interfaces.IFCPlugin

getDescription, initialize, initPlugin, install, shutdown, shutdown, uninstall, validateConfigurationData

Methods inherited from interface de.xima.fc.interfaces.workflow.mixin.IHierarchyValidatingNode

isValidChildCount, isValidChildType, isValidParentType

Methods inherited from interface de.xima.fc.interfaces.workflow.nodes.INodeHandler

getLocalizedTypeName, getRelatedNodeTypes, isCreateProtocolEntryAfterExecution, isReplacePlaceholderBeforeExecution

Methods inherited from interface de.xima.fc.plugin.interfaces.workflow.IPluginWorkflowNode

getXhtmlView

Methods inherited from interface de.xima.fc.interfaces.workflow.execution.IRefinedExecutionResultDescriptor

getAlwaysValueDescriptor, getAttachmentValueDescriptor, getCurrentAttachmentValueDescriptor, getCurrentFileValueDescriptor, getCurrentValueDescriptor, getErrorValueDescriptor, getFileValueDescriptor, getSoftErrorValueDescriptor, getSuccessValueDescriptor

Methods inherited from interface de.xima.fc.workflow.mixin.ISingleBaseDoUntilLoopNodePrototype

getPrototypeModelData

Methods inherited from interface de.xima.fc.interfaces.workflow.mixin.ISingleElementPrototype

getPrototypeSortKey, getPrototypeTags

Methods inherited from interface de.xima.fc.interfaces.workflow.mixin.ISingleNodePrototype

getNodePrototypes

Method Detail

addCurrentValueDescriptorEntries

default void addCurrentValueDescriptorEntries(IValueDescriptorFactory factory,
                                              IRecordValueDescriptorBuilder builder)

Optional method to add additional data to be made available to other workflow actions during a loop iteration. This default implementation does not add any additional data. If you wish to return values and make them available to other actions via variables / placeholders, override this method. If you do, make sure you also modify evaluateDoUntilLoopTest(INodeExecutionParams,IWorkflowLoopDataProviding, int) (or execute(INodeExecutionParams)) and supply the appropriate values.

The current 0-based iteration index always made available, using the getPropertyNameCurrentIndex() as the name.

For example, to indicate that your loop also makes available a cellValue (default value <empty>), you can use:

 public void addCurrentValueDescriptorEntries(IRecordValueDescriptorBuilder builder) {
   return builder //
     .requiredProperty("cellValue", f.string("")) //
     .build();
 

In your beginRepetition() method, you then need to supply a value for the status code and message, which you can do like this:

 static record LoopState(String cellValue) {}

 public startLoop(INodeExecutionParams<TData> params) {
   return new LoopState();
 }

 public beginRepetition(INodeExecutionParams<TData> params, LoopState state, int index) {
   // Read the node properties as configured by the user.
   final var tableName = params.getData().getDatabaseTableName();
   final var column = params.getData().getDatabaseColumn();
   final var prefix = params.getData().getCellValuePrefix();

   // Query the database
   state.cellValue(fetchDatabaseRow(tableName, column, index));

   if (state.cellValue() != null) {
     params.currentValue().withBuilder(b -> b.asRecord().property("cellValue", state.cellValue()));
   }
 }

 public boolean evaluateDoUntilLoopTest(INodeExecutionParams<TData> params, LoopState state, int index) throws AbstractAbruptCompletionException {
   // Do-until loop continues for as long as the row in the database starts with a configured prefix
   return state.cellValue() != null && state.cellValue().startsWith(prefix);
 }
 

Parameters:

factory - Factory for creating the value descriptors for the entries.

builder - Builder for adding additional key-value entries that the loop provides during each iteration.

See Also:

IExecutionResultDescriptor.getCurrentValueDescriptor(IValueDescriptorFactory)

addSuccessValueDescriptorEntries

default void addSuccessValueDescriptorEntries(IValueDescriptorFactory factory,
                                              IRecordValueDescriptorBuilder builder)

Optional method to add additional data to be made available to other workflow actions after the loop has finished. This default implementation does not add any additional data. If you wish to return values and make them available to other actions via variables / placeholders, override this method. If you do, make sure you also modify evaluateDoUntilLoopTest() and supply the appropriate values.

The number of executed iterations is always made available, using the getPropertyNameIterationCount() as the name.

For example, to indicate that your loop may return a totalLength (default value 0), you can use:

 public addSuccessValueDescriptorEntries(IRecordValueDescriptorBuilder builder) {
   return builder //
     .requiredProperty("totalLength", f.integer(0L)) //
     .build();
 

In your startLoop(), return a state object to keep track of the total length:

 static record LoopState(String cellValue, int totalLength) { }

 public LoopState startLoop() {
   return new LoopState();
 }

 In your beginRepetition method, increment the total length for
 with the data from each iteration:

 
 public beginRepetition(INodeExecutionParams<TData> params, LoopState state, int index) {
   // Read the node properties as configured by the user.
   final var tableName = params.getData().getDatabaseTableName();
   final var column = params.getData().getDatabaseColumn();
   final var prefix = params.getData().getCellValuePrefix();

   // Query the database
   state.cellValue(fetchDatabaseRow(tableName, column, index));

   if (state.cellValue() != null) {
     state.totalLength(state.totalLength() + cellValue.length());
   }
 }

 public boolean evaluateDoUntilLoopTest(INodeExecutionParams<TData> params, LoopState state, int index) throws AbstractAbruptCompletionException {
   // Do-until loop continues for as long as the row in the database starts with a configured prefix
   return state.cellValue() != null && state.cellValue().startsWith(prefix);
 }
 

 Finally, use finishLoop() to supply the
 final value.

 
 public boolean finishLoop(INodeExecutionParams<TData> params, LoopState state, int index) throws AbstractAbruptCompletionException {
   params.normalResult().success(b -> b.asRecord().property("totalLength", state.totalLength()));
 }
 

Parameters:

factory - Factory for creating the value descriptors for the entries.

builder - Builder for adding additional key-value entries that the loop returns upon completion.

See Also:

IExecutionResultDescriptor.getSuccessValueDescriptor(IValueDescriptorFactory)

beginRepetition

default void beginRepetition(INodeExecutionParams<TData> params,
                             TState state,
                             int index)
                      throws AbstractAbruptCompletionException

Callback that is invoked at the beginning of each loop iteration. Can be used for custom logic that the loop needs to execute before each iteration. The default implementation is a no-op.

Parameters:

params - Data this do-until loop plugin may use.

state - The custom state as created by startLoop(INodeExecutionParams) when the loop started.

index - 0-based index of the current loop iteration, 0 for the first loop iteration, 1 for the second loop iteration etc.

Throws:

AbstractAbruptCompletionException - When the repetition could not be started. This will abort the workflow, unless handled by an exception handler in the workflow.

endRepetition

default void endRepetition(INodeExecutionParams<TData> params,
                           TState state,
                           int index)
                    throws AbstractAbruptCompletionException

Callback that is invoked at the end of each loop iteration. Can be used for custom logic that the loop needs to execute after each iteration. The default implementation is a no-op.

Parameters:

params - Data this do-until loop plugin may use.

state - The custom state as created by startLoop(INodeExecutionParams) when the loop started.

index - 0-based index of the current loop iteration, 0 for the first loop iteration, 1 for the second loop iteration etc.

Throws:

AbstractAbruptCompletionException - When the repetition could not be finished. This will abort the workflow, unless handled by an exception handler in the workflow.

evaluateDoUntilLoopTest

boolean evaluateDoUntilLoopTest(INodeExecutionParams<TData> params,
                                TState state,
                                int index)
                         throws AbstractAbruptCompletionException

Executes the business logic of this do until loop plugin, and returns whether the do until loop is fulfilled. The loop body is executed for as long as the test returns true.

To provide custom values to other workflow actions for each iteration, use INodeExecutionParams.currentValue(), see also the example in addCurrentValueDescriptorEntries().

When the do until loop test could not be evaluated, you can either just return false or true, or you need to throw an appropriate exception indicating the reason for why the test could not be evaluated. Most commonly this happens when the business logic threw an exception. In this case you should use the provided INodeExecutionParams.throwingException() to build the NodeThrewException, and throw it:

 throw params.throwingResult().cause(exceptionThatWasThrown).build();
 

If you did override getErrorValueDescriptor(IValueDescriptorFactory), you should also include the error code and error details via INodeThrewExceptionBuilder.error(String, Object) or INodeThrewExceptionBuilder.error(String, Object) .

Parameters:

params - Data this do until loop plugin may use. Most importantly, you will need getData(), which contains the configuration as set by the user in the workflow designer.

state - The custom state as created by startLoop(INodeExecutionParams) when the loop started.

index - 0-based index of the current loop iteration, 0 for the first loop iteration, 1 for the second loop iteration etc.

Returns:

true when the do until loop test is fulfilled, or false otherwise.

Throws:

AbstractAbruptCompletionException - When the while loop could not be completed normally. Use the provided INodeExecutionParams.throwingException() and INodeExecutionParams.returningException() to create an instance of the exception.

NodeThrewException - When this exception is thrown, execution of the workflow task is aborted, unless an exception handler was defined in the workflow configuration.

NodeReturnedException - When this exception is thrown, the while loop is judged to have been executed successfully, and execution of the workflow task is stopped.

RuntimeException - A runtime exception may be thrown to indicate an unforeseen error, such as general database errors. For all errors you expect to happen, you should throw an appropriate NodeThrewException with the details of the exception. When a runtime exception is thrown, it is wrapped in a NodeThrewException and treated as if that exception had been thrown.

RuntimeException - A runtime exception may be thrown to indicate an unforeseen error, such as general database errors. For all errors you expect to happen, you should throw an appropriate NodeThrewException with the details of the exception. When a runtime exception is thrown, it is wrapped in a NodeThrewException and treated as if that exception had been thrown.

execute

default INormalCompletionResult execute(INodeExecutionParams<TData> params)
                                 throws AbstractAbruptCompletionException

Evaluates the do until loop test of this plugin, and executes the loop body for as long as the do until loop test holds true. You should not need to override this method, instead, implements evaluateDoUntilLoopTest(INodeExecutionParams, IWorkflowLoopDataProviding, int).

Specified by:

execute in interface INodeHandler<TData extends BaseDoUntilLoopProps>

Parameters:

params - Data this do until loop plugin may use.

Returns:

The values returned by this do until loop, as specified by getSuccessValueDescriptor(IValueDescriptorFactory)}. Any value not set explicitly will use its default value from the success vale descriptor.

Throws:

AbstractAbruptCompletionException - When the node's execution did not finish normally, see below for subclasses.

NodeThrewException - If this exception was thrown by the execute method of the given node. Indicates that a node could not be completed successfully. This exception can be caught by control flow nodes with custom error handling, such as a try-catch node.

NodeReturnedException - If this exception was thrown by the execute method of the given node. Indicates that the node wishes to return, i.e. to stop the execution of the current processing chain (="function"). This exception can be caught by control flow nodes with custom finalization handling, such as a try-finally node (which should rethrow this exception afterwards).

NodeTransferredControlException - If this exception was thrown by the execute method of the given node. Indicates that a control transfer should take place. The matching node for the control transfer target should catch this exception and proceed according to the type of the control transfer.

ExecutionAbortedError - When the execution of the task was aborted, such as when certain limits were exceeded. Usually you should not catch this exception and allow it to propagate upwards.

extractDescription

default String extractDescription(TData data)

Description copied from interface: IElementHandler

Retrieves the name that will be stored as AWorkflowElement.getDescription(). For example, actions may let the user enter a description for the action, which would be returned by this method. A condition node may an explanation of the test condition as the description.

The default implementation checks whether the IElementHandler.getDataModelClass() implements IDescriptionProviding and if it does, returns IDescriptionProviding.getDescription(). Otherwise returns an empty string.

Specified by:

extractDescription in interface IElementHandler<TData extends BaseDoUntilLoopProps,TState extends IWorkflowLoopDataProviding>

Parameters:

data - The data of the workflow element for which to retrieve the description.

Returns:

The description of the workflow element with the given data.

extractName

default String extractName(TData data)

Description copied from interface: IElementHandler

Retrieves the name that will be stored as AWorkflowElement.getName(). For example, actions may let the user enter the name of the action, which would be returned by this method. A condition node may use a summary of the test condition as the name. A button trigger event may use the name of the button.

The default implementation checks whether the IElementHandler.getDataModelClass() implements INameProviding and if it does, returns INameProviding.getName().

Specified by:

extractName in interface IElementHandler<TData extends BaseDoUntilLoopProps,TState extends IWorkflowLoopDataProviding>

Parameters:

data - The data of the workflow element for which to retrieve the name.

Returns:

The name of the workflow element with the given data.

finishLoop

default void finishLoop(INodeExecutionParams<TData> params,
                        TState state,
                        int totalCount)

Called once at the end after all iterations are done just before the end of the loop's execution. You can use this method e.g. to provide success results derived from the accumulated state. The default implementation is a no-op.

Parameters:

params - Data this do until loop plugin may use. Most importantly, you will need getData(), which contains the configuration as set by the user in the workflow designer.

state - The custom state as created by startLoop(INodeExecutionParams) when the loop started.

totalCount - The total number of loop iterations that were executed.

getAlwaysValueDescriptor

default IValueDescriptor<?,? extends IValueBuilder<?>> getAlwaysValueDescriptor(IValueDescriptorFactory factory)

This default implementation returns a void value descriptor. This is appropriate when this plugin does not need to return any values. If you wish to return values (and make them available to other actions via variables / placeholders), override this method. If you do, make sure you also modify execute(INodeExecutionParams) and supply the appropriate values upon execution.

Specified by:

getAlwaysValueDescriptor in interface IExecutionResultDescriptor

Parameters:

factory - Factory that may be used for creating the descriptor. You may also use ValueDescriptorFactory.getInstance() if you wish to cache the descriptor in a static or instance field.

Returns:

The value descriptor for that data that is made available to the workflow when the node is executed, regardless of whether is succeeded or failed.

See Also:

IExecutionResultDescriptor.getAlwaysValueDescriptor(IValueDescriptorFactory)

getCurrentValueDescriptor

default IValueDescriptor<?,? extends IValueBuilder<?>> getCurrentValueDescriptor(IValueDescriptorFactory factory)

Normally you do not need to override this method, override addCurrentValueDescriptorEntries() instead. The default implementation always adds an entry with the current iteration index, using getPropertyNameCurrentIndex() as the entry's name.

Specified by:

getCurrentValueDescriptor in interface IExecutionResultDescriptor

Parameters:

factory - Factory that may be used for creating the descriptor. Instead of the factory passed in to this method, you may also use ValueDescriptorFactory.getInstance() if you wish to cache the descriptor in a static or instance field.

Returns:

The descriptor for data published by the node while it is being executed.

getDataModelClass

default Class<? extends TData> getDataModelClass()

This default implementation attempts to read the type of the TData parameter via reflection. If that does not work, or you need to optimize, override this method and return the type directly.

Specified by:

getDataModelClass in interface IElementHandler<TData extends BaseDoUntilLoopProps,TState extends IWorkflowLoopDataProviding>

Returns:

The class corresponding to the type parameter TData.

See Also:

IElementHandler.getDataModelClass()

getDescription

default String getDescription(Locale locale)

The default implementation returns the localized value of the getI18nKeyDescription() in the getResourceBundle(Locale). When no value exists for that key, returns an empty string (= no description).

Specified by:

getDescription in interface IFCPlugin

Parameters:

locale - The locale for which to get the description.

Returns:

An HTML markup string with the description for this plugin, or null if no description is available.

See Also:

IFCPlugin.getDescription()

getDisplayName

default String getDisplayName(Locale locale)

The default implementation returns the localized value of the getI18nKeyDisplayName() in the getResourceBundle(Locale). When no value exists for that key, returns the getName() of this plugin.

Specified by:

getDisplayName in interface IFCPlugin

Specified by:

getDisplayName in interface INamedUiElement

Parameters:

locale - The locale to get the display name for.

Returns:

The display name of this element in the given locale.

See Also:

IFCPlugin.getDisplayName(Locale)

getErrorValueDescriptor

default IUnionValueDescriptor<String> getErrorValueDescriptor(IValueDescriptorFactory factory)

This default implementation simply returns no error codes. When the do until loop test can have errors, override this method and use IValueDescriptorFactory.unionStringBuilder() to add the errors.

 public IUnionValueDescriptor<String> getSoftErrorValueDescriptor(IValueDescriptorFactory f) {
   return f.recordBuilder() //
     .add("FILE_NOT_FOUND", f.recordBuilder().requiredProperty("file", f.string("")).build()) //
     .add("NETWORK_ERROR", f.recordBuilder().requiredProperty("url", f.string("")).build()) //
     .build();
 

Note that it is recommended that you keep the available error codes in an enum, so you can reuse them later.

In your execute(INodeExecutionParams) method, you can then add a soft error when necessary while building an error result:

 public boolean executeDoUntilLoopTest(INodeExecutionParams<TData> params, TState state, int index) throws AbstractAbruptCompletionException {
   try {
     // Run business logic for the do until loop test...
     return true;
   }
   catch (final IOException e) {
     // Add the error
     final var errorData = new HashMap<String, Object>();
     errorData.put("file", fileName);
     throw params.throwingException().error("FILE_NOT_FOUND", errorData).cause(e).build();
   }
 }
 

Instead of the factory passed in to this method, you may also use ValueDescriptorFactory.getInstance() if you wish to cache the descriptor in a static or instance field. *

Specified by:

getErrorValueDescriptor in interface IExecutionResultDescriptor

Parameters:

factory - Factory that may be used for creating the descriptor. You may also use ValueDescriptorFactory.getInstance() if you wish to cache the descriptor in a static or instance field.

Returns:

The value descriptor for the data that is made available to the workflow when the execution of the node failed (such as by throwing an exception).

See Also:

IExecutionResultDescriptor.getErrorValueDescriptor(IValueDescriptorFactory)

getI18nKeyActionLabel

default String getI18nKeyActionLabel()

Returns:

The i18n key for the name of the do until loop, as shown in the workflow designer. Defaults to the getI18nKeyDisplayName().

getI18nKeyActionSearchText

default String getI18nKeyActionSearchText()

Returns:

The i18n key for the search text of the do until loop, not shown in the UI but used for filtering. Defaults to "getName().searchtext".

getI18nKeyActionSubLabel

default String getI18nKeyActionSubLabel()

Returns:

The i18n key for the sub label of the do until loop, as shown in the workflow designer below the name of the item. Defaults to "getName().sublabel".

getI18nKeyActionTitle

default String getI18nKeyActionTitle()

Returns:

The i18n key for the title of the do until loop, as shown in the workflow designer when hovering over the item with the mouse. Defaults to "getName().title".

getI18nKeyDescription

default String getI18nKeyDescription()

Returns:

The i18n key for the description of this plugin. Defaults to "getName().desc".

getI18nKeyDisplayName

default String getI18nKeyDisplayName()

Returns:

The i18n key for the display name of this plugin, as shown in the plugin configuration backend menu. Defaults to "getName().name".

getLoopBodyChildIndex

default int getLoopBodyChildIndex()

Specified by:

getLoopBodyChildIndex in interface IBaseDoUntilLoopClientHandlerNode<TData extends BaseDoUntilLoopProps>

Specified by:

getLoopBodyChildIndex in interface IExecutingLikePostTestLoopNode<TData extends BaseDoUntilLoopProps>

Returns:

Index of the child representing the loop body.

getMainCategory

default IElementCategory getMainCategory(IGetElementPrototypesParams params)

Specified by:

getMainCategory in interface ISingleElementPrototype<TData extends BaseDoUntilLoopProps,TState extends IWorkflowLoopDataProviding>

Parameters:

params - Parameters with the current client, locale, entity context etc.

Returns:

IElementCategory element's main category, which is used for grouping the elements.

getMainPluginBeanClass

default Class<? extends INodePropertyPluginBean<TData>> getMainPluginBeanClass()

Returns:

The class of the bean that should be made available in the getPropertiesViewXhtml() page. When this returns null, no bean is made available This is usually sufficient for most simple use cases, see IElementHandler.getPropertiesViewXhtml() for further details.

getName

String getName()

Description copied from interface: IFCPlugin

Getter for the name of this plugin. This is a technical name that should not appear on the user interface. Implement IFCPlugin.getDisplayName(Locale) for the name that should be shown to the user.

Specified by:

getName in interface IFCPlugin

Specified by:

getName in interface INameProviding

Returns:

String The name of this plugin.

getNodeHandler

default INodeHandler<TData> getNodeHandler()

Specified by:

getNodeHandler in interface IPluginWorkflowNode

Returns:

The node handler that implements all the logic required by the workflow node. This lets you customize all features available to built-in workflow nodes.

getPluginInitializeData

IPluginInitializeData getPluginInitializeData()

Returns:

The IPluginInitializeData, as they were passed to IFCPlugin.initialize(IPluginInitializeData). Implementation should usually just store the data in a private volatile field and return it in this method.

getPropertiesBeanClass

default Class<? extends INodePropertiesBean<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 require 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 extends BaseDoUntilLoopProps,TState extends IWorkflowLoopDataProviding>

Specified by:

getPropertiesBeanClass in interface INodeHandler<TData extends BaseDoUntilLoopProps>

Returns:

The class of the bean to use for editing a workflow node's properties.

See Also:

IElementHandler.getPropertiesViewXhtml()

getPropertiesViewXhtml

default URL getPropertiesViewXhtml()
                            throws MalformedURLException

This default implementation returns the XHTML page located at getPropertiesViewXhtmlPath()/getPropertiesViewXhtmlName().

Specified by:

getPropertiesViewXhtml in interface IElementHandler<TData extends BaseDoUntilLoopProps,TState extends IWorkflowLoopDataProviding>

Returns:

Path to the XHTML view. If the action can be configured, this must not return null. If you do return null, it will be treated as an error and an appropriate message is displayed to the user informing them that the properties panel could not be loaded. If the action cannot be configured (i.e. when the action is not selectable), this should return null.

Throws:

MalformedURLException - This exception is declared for convenience - normally you would use new URL(String) with a constant URL string that should not throw. In case an exception is thrown, it is treated the same as if this returned null.

See Also:

IElementHandler.getPropertiesViewXhtml()

getPropertiesViewXhtmlName

String getPropertiesViewXhtmlName()

Returns:

The file name (without the path) to the XHTML page with the custom UI. The file extension .xhtml is added automatically if the returned name does not contain it already.

See Also:

getPropertiesViewXhtmlPath()

getPropertiesViewXhtmlPath

default String getPropertiesViewXhtmlPath()

Returns:

The path (without the file name) to the XHTML page with the custom UI. Defaults to WEB-INF/ui. That is, you should put the file in src/main/resources/WEB-INF/ui.

See Also:

getPropertiesViewXhtmlName()

getPropertyNameCurrentIndex

default String getPropertyNameCurrentIndex()

Optional method to change the name of the property that can be used to access the current loop iteration index by other actions in the workflow. The default implementation returns index.

Returns:

Name of the property for accessing the current loop index.

getPropertyNameIterationCount

default String getPropertyNameIterationCount()

Optional method to change the name of the property that can be used to access the total number of iterations by other actions in the workflow once the loop has finished. The default implementation returns count.

Returns:

Name of the property for accessing the loop iteration count.

getPrototypeElement

default WorkflowNode getPrototypeElement(IGetElementPrototypesParams params)

Specified by:

getPrototypeElement in interface ISingleElementPrototype<TData extends BaseDoUntilLoopProps,TState extends IWorkflowLoopDataProviding>

Specified by:

getPrototypeElement in interface ISingleNodePrototype<TData extends BaseDoUntilLoopProps>

Parameters:

params - Parameters with the current client, locale, entity context etc.

Returns:

The workflow element that is used as a prototype. The default implementation simply creates a new workflow element with the IWorkflowElementTypeProviding.getType(). Usually there is no reason to override this method.

getPrototypeIcon

default IGuiIcon getPrototypeIcon(IGetElementPrototypesParams params)

This default implementation returns an icon with arrows arranged in a circle, which is the default icon for a while loop plugin.

Specified by:

getPrototypeIcon in interface ISingleElementPrototype<TData extends BaseDoUntilLoopProps,TState extends IWorkflowLoopDataProviding>

Parameters:

params - Parameters with the current client, locale, entity context etc.

Returns:

The icon for the element prototype, shown in the element drawer panel to the left of the workflow designer. See IElementPrototypeDescriptor.getIcon().

See Also:

ISingleElementPrototype.getPrototypeIcon(IGetElementPrototypesParams)

getPrototypeLabel

default String getPrototypeLabel(IGetElementPrototypesParams params)

This default implementation returns the localized value of the getI18nKeyActionLabel() in the getResourceBundle(Locale). If no localized value exists for that key, defaults the getName() of this plugin.

Specified by:

getPrototypeLabel in interface ISingleElementPrototype<TData extends BaseDoUntilLoopProps,TState extends IWorkflowLoopDataProviding>

Parameters:

params - Parameters with the current client, locale, entity context etc.

Returns:

The icon for the element prototype, shown in the element drawer panel to the left of the workflow designer. See IElementPrototypeDescriptor.getLabel().

See Also:

ISingleElementPrototype.getPrototypeLabel(IGetElementPrototypesParams)

getPrototypeSearchText

default String getPrototypeSearchText(IGetElementPrototypesParams params)

This default implementation returns the localized value of the getI18nKeyActionSearchText() in the getResourceBundle(Locale). If no localized value exists for that key, no title is used.

Specified by:

getPrototypeSearchText in interface ISingleElementPrototype<TData extends BaseDoUntilLoopProps,TState extends IWorkflowLoopDataProviding>

Parameters:

params - Parameters with the current client, locale, entity context etc.

Returns:

The search text for the element prototype, never shown to the user but used for filtering. See IElementPrototypeDescriptor.getSearchText().

See Also:

ISingleElementPrototype.getPrototypeSearchText(IGetElementPrototypesParams)

getPrototypeSubLabel

default String getPrototypeSubLabel(IGetElementPrototypesParams params)

This default implementation returns the localized value of the getI18nKeyActionSubLabel() in the getResourceBundle(Locale). If no localized value exists for that key, no sub label is used.

Specified by:

getPrototypeSubLabel in interface ISingleElementPrototype<TData extends BaseDoUntilLoopProps,TState extends IWorkflowLoopDataProviding>

Parameters:

params - Parameters with the current client, locale, entity context etc.

Returns:

The sub label for the element prototype, shown in the element drawer panel to the left of the workflow designer. See IElementPrototypeDescriptor.getLabel().

See Also:

ISingleElementPrototype.getPrototypeSubLabel(IGetElementPrototypesParams)

getPrototypeTitle

default String getPrototypeTitle(IGetElementPrototypesParams params)

This default implementation returns the localized value of the getI18nKeyActionTitle() in the getResourceBundle(Locale). If no localized value exists for that key, no title is used.

Specified by:

getPrototypeTitle in interface ISingleElementPrototype<TData extends BaseDoUntilLoopProps,TState extends IWorkflowLoopDataProviding>

Parameters:

params - Parameters with the current client, locale, entity context etc.

Returns:

The title for the element prototype, shown in the element drawer panel to the left of the workflow designer. See IElementPrototypeDescriptor.getLabel().

See Also:

ISingleElementPrototype.getPrototypeTitle(IGetElementPrototypesParams)

getResourceBundle

default ResourceBundle getResourceBundle(Locale locale)

This default implementation attempts to read the resource bundle from the getResourceBundlePath(). In most cases this is fine and does not have to be overridden, although you may want to override the getResourceBundlePath().

Specified by:

getResourceBundle in interface IElementHandler<TData extends BaseDoUntilLoopProps,TState extends IWorkflowLoopDataProviding>

Specified by:

getResourceBundle in interface IResourceBundleLocator

Parameters:

locale - A locale, for which a resource bundle shall be retrieved. Must not be null.

Returns:

The resource bundle to use for localized messages.

See Also:

IElementHandler.getResourceBundle(Locale)

getResourceBundlePath

default String getResourceBundlePath()

Returns:

The path to the resource bundle with the localized message for this plugin. Defaults to WEB-INF/properties/i18n. That is, you should create the properties files src/main/resources/WEB-INF/properties/i18n_en.properties (for English), src/main/resources/WEB-INF/properties/i18n_de.properties (for German), etc.

getSoftErrorValueDescriptor

default IUnionValueDescriptor<String> getSoftErrorValueDescriptor(IValueDescriptorFactory factory)

This default implementation simply returns no error codes. When the do until loop can have soft errors, override this method and use IValueDescriptorFactory.unionStringBuilder() to add the soft errors.

 public IUnionValueDescriptor<String> getSoftErrorValueDescriptor(IValueDescriptorFactory f) {
   return f.recordBuilder() //
     .add("FILE_NOT_FOUND", f.recordBuilder().requiredProperty("file", f.string("")).build()) //
     .add("NETWORK_ERROR", f.recordBuilder().requiredProperty("url", f.string("")).build()) //
     .build();
 

Note that it is recommended that you keep the available soft error codes in an enum, so you can reuse them later.

In your execute(INodeExecutionParams) method, you can then add a soft error when necessary, which you can do like this:

 public boolean executeDoUntilLoopTest(INodeExecutionParams<TData> params) throws AbstractAbruptCompletionException {
   try {
     // Run business logic...
     return true;
   }
   catch (final IOException e) {
     // Add the soft error
     final var errorData = new HashMap<String, Object>();
     errorData.put("file", fileName);
     params.softError("FILE_NOT_FOUND", e, b -> b.value(errorData))
     return false;
   }
 }
 

Instead of the factory passed in to this method, you may also use ValueDescriptorFactory.getInstance() if you wish to cache the descriptor in a static or instance field. *

Specified by:

getSoftErrorValueDescriptor in interface IExecutionResultDescriptor

Parameters:

factory - Factory that may be used for creating the descriptor. You may also use ValueDescriptorFactory.getInstance() if you wish to cache the descriptor in a static or instance field.

Returns:

The value descriptor for the data that is made available to the workflow when the execution of the node was successful, but contains one or more soft errors.

See Also:

IExecutionResultDescriptor.getSoftErrorValueDescriptor(IValueDescriptorFactory)

getSubCategory

default IElementCategory getSubCategory(IGetElementPrototypesParams params)

Description copied from interface: ISingleElementPrototype

Optional sub category. When not set or this returns null, the element is shown under the category miscellaneous.

Specified by:

getSubCategory in interface ISingleElementPrototype<TData extends BaseDoUntilLoopProps,TState extends IWorkflowLoopDataProviding>

Parameters:

params - Parameters with the current client, locale, entity context etc.

Returns:

IElementCategory element's sub category, which is used for grouping the element within the given main group.

getSuccessValueDescriptor

default IValueDescriptor<?,? extends IValueBuilder<?>> getSuccessValueDescriptor(IValueDescriptorFactory factory)

Normally you do not need to override this method, override addSuccessValueDescriptorEntries() instead. The default implementation always adds an entry with the number of executed loop iteration, using getPropertyNameIterationCount() as the entry's name.

Specified by:

getSuccessValueDescriptor in interface IExecutionResultDescriptor

Parameters:

factory - Factory that may be used for creating the descriptor. Instead of the factory passed in to this method, you may also use ValueDescriptorFactory.getInstance() if you wish to cache the descriptor in a static or instance field.

Returns:

The data provided by the node after having been executed successfully.

getSupportedControlTransferTypes

default Set<String> getSupportedControlTransferTypes()

Description copied from interface: INodeHandler

Returns the set of control transfer types that this node can handle. See EStandardControlTransferType for a list of built-in transfer types.

If this method returns a non-empty set, the execute method should catch NodeTransferredControlException. If its control transfer type is one of the supported types, it should handle that control transfer accordingly. Otherwise, it should propagate the exception upwards by rethrowing it.

This method is also used by control transfer nodes (e.g. the built-in FC_BREAK or FC_CONTINUE) to decide which nodes are valid targets.

Specified by:

getSupportedControlTransferTypes in interface INodeHandler<TData extends BaseDoUntilLoopProps>

Returns:

The control transfer types that this node can handle.

See Also:

for a list of built-in control transfer types.

getType

default String getType()

This default implementation simply returns the getName() of the plugin as the type. Make sure that the name is unique. It is recommended you hard-code the name / type, as any change will result in broken backwards compatibility. In particular we advice against using Class.getCanonicalName() etc., as a refactoring would then break your plugin.

Specified by:

getType in interface IWorkflowElementTypeProviding

Returns:

The type of the workflow element that determines how the workflow element behaves. Usually there is a registered handler for each type.

getUnmanagedBeans

default Iterable<Class<? extends IPluginWorkflowNodeBean>> getUnmanagedBeans()

Description copied from interface: IPluginGenericCustomGUI

This must return a list of backing bean classes that control the user interface and are required by the XHTML Facelet view. A new instance of the bean will be created automatically when the view is opened. Make sure each bean has got a no-argument constructor or instantiation will fail.

Each bean should be annotated with Named. If this annotation is not present or no name is specified, the name defaults to the simple name of the bean class, with the first character changed to lower case.

Also, each bean needs to be annotated one of the following scopes: @RequestScoped, @ViewScoped, @SessionScoped, or @ApplicationScoped. Note that it depends on the type of plugin which scopes are actually supported (most plugins expect @ViewScoped beans). In case you do not specify a scope, an appropriate scope will be determined automatically.

Please note that the beans are fundamentally unmanaged - functionality specific to managed CDI beans may not be supported, depending on the type of plugin. Certain features of CDI managed beans may be supported partially, depending on the type of plugin, but may work slightly differently. This includes, but is not limited to:

• The exact timing at which PostConstruct and PreDestroy are called may differ.
• A field marked with Inject may not work with all values allowed by the CDI specification, and may not perform certain validation passes such as the check for circular dependencies. Also, no new bean instances will be created when those beans have not yet been created as part of the current page.

Specified by:

getUnmanagedBeans in interface IPluginGenericCustomGUI<TData extends BaseDoUntilLoopProps>

Returns:

A list of unmanaged bean classes required by the Facelet page.

getVersion

default String getVersion()

Instead of the FORMCYCLE version, this default implementation returns the current version of this plugin. The version is read from the MANIFEST.MF file in the plugin JAR file. Make sure that the manifest contains an appropriate version entry, e.g.:

 Implementation-Version = 3.1.4
 

We recommend that you use version numbers that conform to the format and semantics as laid out by SemVer (semantic version).

Specified by:

getVersion in interface IElementHandler<TData extends BaseDoUntilLoopProps,TState extends IWorkflowLoopDataProviding>

Returns:

The version of this plugin.

See Also:

IElementHandler.getVersion()

isCreateProtocolEntryAfterExecution

default boolean isCreateProtocolEntryAfterExecution(ICreateProtocolEntryAfterExecutionParams params)

Description copied from interface: INodeHandler

Controls whether a protocol entry is created after the node was executed.

The default implementation returns true iff result was created by the current node.

When some action throws an exception, all parent control flow node such as if-else statements also throw an exception. This would result in multiple protocol entries for a single error.

Specified by:

isCreateProtocolEntryAfterExecution in interface INodeHandler<TData extends BaseDoUntilLoopProps>

Parameters:

params - Parameters with the node that was executed and the result of the node's execution.

Returns:

true to create a protocol entry, or false otherwise.

startLoop

default TState startLoop(INodeExecutionParams<TData> params)

Called once at the beginning before the loop iterations are started. You can use this method to provide a custom state object that is available during the entire duration of the loop's execution; and is passed on to evaluateDoUntilLoopTest() as well as finishLoop()

The default implementation simply returns null.

Parameters:

params - Data this do until loop plugin may use. Most importantly, you will need getData(), which contains the configuration as set by the user in the workflow designer.

Returns:

A custom state object that is passed available during the loop's execution.