Package com.smartgwt.client.util.workflow

Class ProcessElement

java.lang.Object
com.smartgwt.client.core.BaseClass
com.smartgwt.client.util.workflow.ProcessElement
All Implemented Interfaces:
HasHandlers
Direct Known Subclasses:
ComponentTask, DecisionTask, EndProcessTask, LogOutTask, MultiDecisionTask, ProcessSequence, ResetPasswordTask, SendTransactionTask, ShowMessageTask, ShowNotificationTask, StartTransactionTask, Task, UserConfirmationGateway, UserConfirmationTask
public class ProcessElement extends BaseClass
A ProcessElement is an abstract superclass for elements involved in a Process, such as a Task or DecisionTask.

  • Constructor Details

    • ProcessElement

      public ProcessElement()

    • ProcessElement

      public ProcessElement(JavaScriptObject jsObj)

    • ProcessElement

      public ProcessElement(String ID)

    • ProcessElement

      public ProcessElement(String ID, String nextElement)

  • Method Details

    • getOrCreateRef

      public static ProcessElement getOrCreateRef(JavaScriptObject jsObj)

    • setJavaScriptObject

      public void setJavaScriptObject(JavaScriptObject jsObj)
      Overrides:
      setJavaScriptObject in class BaseClass

    • create

      public JavaScriptObject create()
      Specified by:
      create in class BaseClass

    • isCreated

      public boolean isCreated()
      Overrides:
      isCreated in class BaseClass

    • getJsObj

      public JavaScriptObject getJsObj()
      Overrides:
      getJsObj in class BaseClass

    • getOrCreateJsObj

      public JavaScriptObject getOrCreateJsObj()
      Overrides:
      getOrCreateJsObj in class BaseClass

    • setBindOutput

      public ProcessElement setBindOutput(String bindOutput) throws IllegalStateException
      When set, the output of the task will be automatically bound to the specified value in the process state.

      See taskInputExpressions for details on the transient state outputs.

      Parameters:
      bindOutput - New bindOutput value. Default value is null
      Returns:
      ProcessElement instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getBindOutput

      public String getBindOutput()
      When set, the output of the task will be automatically bound to the specified value in the process state.

      See taskInputExpressions for details on the transient state outputs.

      Returns:
      Current bindOutput value. Default value is null

    • setClassDescription

      public ProcessElement setClassDescription(String classDescription) throws IllegalStateException
      Optional description of the general nature of the kinds of tasks this this process element performs. Not to be confused with description which describes what the specific instance of the process element has been configured to do.

      For example, the classDescription for a task to disable a field might be "disables a field" whereas the description for a concrete instance might be "disables the 'shipTo' field in the 'ordering' form".

      Used by editor to display additional details along with typeTitle.

      Parameters:
      classDescription - New classDescription value. Default value is null
      Returns:
      ProcessElement instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getClassDescription

      public String getClassDescription()
      Optional description of the general nature of the kinds of tasks this this process element performs. Not to be confused with description which describes what the specific instance of the process element has been configured to do.

      For example, the classDescription for a task to disable a field might be "disables a field" whereas the description for a concrete instance might be "disables the 'shipTo' field in the 'ordering' form".

      Used by editor to display additional details along with typeTitle.

      Returns:
      Current classDescription value. Default value is null

    • setDescription

      public ProcessElement setDescription(String description) throws IllegalStateException
      Optional description for this specific instance of process element.
      Parameters:
      description - New description value. Default value is null
      Returns:
      ProcessElement instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getDescription

      public String getDescription()
      Optional description for this specific instance of process element.
      Returns:
      Current description value. Default value is null

    • setEditorType

      public ProcessElement setEditorType(String editorType) throws IllegalStateException
      Editor type used to edit instances of this type of process element.
      Parameters:
      editorType - New editorType value. Default value is null
      Returns:
      ProcessElement instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getEditorType

      public String getEditorType()
      Editor type used to edit instances of this type of process element.
      Returns:
      Returns the workflow task editor type to be used edit instances of this type of process element. The default implementation returns this.editorType but a custom override could determine an editor type based on the property values. Default value is null

    • setForceSingle

      public ProcessElement setForceSingle(Boolean forceSingle)
      Should multiple record processing be suppressed for this task instance? This property can be set at any time is checked before executing the task and after each execution during processing of multiple last task output records.

      Note that since this property applies to an instance of a task that could be used multiple times in a process (by branching) care should be taken to restore the property value after execution completes. See completeElement() or reset().

      Parameters:
      forceSingle - New forceSingle value. Default value is null
      Returns:
      ProcessElement instance, for chaining setter calls

    • getForceSingle

      public Boolean getForceSingle()
      Should multiple record processing be suppressed for this task instance? This property can be set at any time is checked before executing the task and after each execution during processing of multiple last task output records.

      Note that since this property applies to an instance of a task that could be used multiple times in a process (by branching) care should be taken to restore the property value after execution completes. See completeElement() or reset().

      Returns:
      Current forceSingle value. Default value is null

    • setID

      public ProcessElement setID(String ID) throws IllegalStateException
      Optional ID for this process element, allowing it to be referred to from Decisions, or as the Process.startElement. See ProcessSequence and Process to understand when this is required or can be omitted.

      Unlike Canvas.ID a processElement's is a not a globally unique variable, it need only by unique within its process.

      When assigned an ID, a processElement can be retrieve via Process.getElement().

      Overrides:
      setID in class BaseClass
      Parameters:
      ID - New ID value. Default value is null
      Returns:
      ProcessElement instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getID

      public String getID()
      Optional ID for this process element, allowing it to be referred to from Decisions, or as the Process.startElement. See ProcessSequence and Process to understand when this is required or can be omitted.

      Unlike Canvas.ID a processElement's is a not a globally unique variable, it need only by unique within its process.

      When assigned an ID, a processElement can be retrieve via Process.getElement().

      Overrides:
      getID in class BaseClass
      Returns:
      Current ID value. Default value is null

    • setMockMode

      public ProcessElement setMockMode(Boolean mockMode)
      Enable mock mode on the task? If Process.mockMode is enabled, setting this property to false disables mockMode on this task only. Otherwise, mock mode can be enabled on this task by setting it to true.

      Note that it is up to each task determine what effect mock mode has.

      Parameters:
      mockMode - New mockMode value. Default value is null
      Returns:
      ProcessElement instance, for chaining setter calls

    • getMockMode

      public Boolean getMockMode()
      Enable mock mode on the task? If Process.mockMode is enabled, setting this property to false disables mockMode on this task only. Otherwise, mock mode can be enabled on this task by setting it to true.

      Note that it is up to each task determine what effect mock mode has.

      Returns:
      Current mockMode value. Default value is null

    • setNextElement

      public ProcessElement setNextElement(String nextElement) throws IllegalStateException
      Next sequence or element to execute after this one completes.

      nextElement does not need to be specified on most elements if you use sequences.

      Note that if there is both a sequence and a normal element with the same name in the current Process, the sequence will be used.

      Parameters:
      nextElement - New nextElement value. Default value is null
      Returns:
      ProcessElement instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getNextElement

      public String getNextElement()
      Next sequence or element to execute after this one completes.

      nextElement does not need to be specified on most elements if you use sequences.

      Note that if there is both a sequence and a normal element with the same name in the current Process, the sequence will be used.

      Returns:
      Current nextElement value. Default value is null

    • setPassThruOutput

      public ProcessElement setPassThruOutput(Boolean passThruOutput) throws IllegalStateException
      Does this processElement pass through output from the last executed task (i.e. transient state)?

      See taskInputExpressions for details on the transient state outputs.

      Note that this property does not affect the task at all but is an indicator to the user and to the workflow editor of the behavior of the task as coded (See Process.passThruTaskOutput()).

      Parameters:
      passThruOutput - New passThruOutput value. Default value is true
      Returns:
      ProcessElement instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getPassThruOutput

      public Boolean getPassThruOutput()
      Does this processElement pass through output from the last executed task (i.e. transient state)?

      See taskInputExpressions for details on the transient state outputs.

      Note that this property does not affect the task at all but is an indicator to the user and to the workflow editor of the behavior of the task as coded (See Process.passThruTaskOutput()).

      Returns:
      Current passThruOutput value. Default value is true

    • setSupportsMultipleInputRecords

      public ProcessElement setSupportsMultipleInputRecords(Boolean supportsMultipleInputRecords) throws IllegalStateException
      Does this processElement support being called multiple times for multiple records in the last task output?

      By default a processElement is executed exactly once, however, for a task that can process records from the last task output it can be useful to handle each incoming record individually. Setting this property indicates to the process that if the last task output is an array, it should be executed once per value in the array. Normal processing of taskInputExpressions or use of Process.getLastTaskOutput() will have exactly one record except uses of the output for criteria values where the full output is used at once.

      Processing of the task can determine that multiple incoming records should not result in multiple calls and set forceSingle. For example, a task that uses last task output for a criteria or for values should set forceSingle=true when a criteria is used because multiple calls do not make sense.

      Parameters:
      supportsMultipleInputRecords - New supportsMultipleInputRecords value. Default value is null
      Returns:
      ProcessElement instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getSupportsMultipleInputRecords

      public Boolean getSupportsMultipleInputRecords()
      Does this processElement support being called multiple times for multiple records in the last task output?

      By default a processElement is executed exactly once, however, for a task that can process records from the last task output it can be useful to handle each incoming record individually. Setting this property indicates to the process that if the last task output is an array, it should be executed once per value in the array. Normal processing of taskInputExpressions or use of Process.getLastTaskOutput() will have exactly one record except uses of the output for criteria values where the full output is used at once.

      Processing of the task can determine that multiple incoming records should not result in multiple calls and set forceSingle. For example, a task that uses last task output for a criteria or for values should set forceSingle=true when a criteria is used because multiple calls do not make sense.

      Returns:
      Current supportsMultipleInputRecords value. Default value is null

    • setTypeTitle

      public ProcessElement setTypeTitle(String typeTitle) throws IllegalStateException
      Optional short, descriptive title for this process element. Used by an editor as a title for process elements of this type.
      Parameters:
      typeTitle - New typeTitle value. Default value is null
      Returns:
      ProcessElement instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getTypeTitle

      public String getTypeTitle()
      Optional short, descriptive title for this process element. Used by an editor as a title for process elements of this type.
      Returns:
      Current typeTitle value. Default value is null

    • setUndefinedComponentMessage

      public ProcessElement setUndefinedComponentMessage(String undefinedComponentMessage) throws IllegalStateException
      The default message to be reported with getInvalidTaskMessage() when a target component property is not defined.
      Parameters:
      undefinedComponentMessage - New undefinedComponentMessage value. Default value is "${propertyName} is not defined"
      Returns:
      ProcessElement instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getUndefinedComponentMessage

      public String getUndefinedComponentMessage()
      The default message to be reported with getInvalidTaskMessage() when a target component property is not defined.
      Returns:
      Current undefinedComponentMessage value. Default value is "${propertyName} is not defined"

    • setUnresolvedComponentMessage

      public ProcessElement setUnresolvedComponentMessage(String unresolvedComponentMessage) throws IllegalStateException
      The default message to be reported with getInvalidTaskMessage() when a target component cannot be resolved.
      Parameters:
      unresolvedComponentMessage - New unresolvedComponentMessage value. Default value is "${propertyName} '${id}' could not be resolved"
      Returns:
      ProcessElement instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getUnresolvedComponentMessage

      public String getUnresolvedComponentMessage()
      The default message to be reported with getInvalidTaskMessage() when a target component cannot be resolved.
      Returns:
      Current unresolvedComponentMessage value. Default value is "${propertyName} '${id}' could not be resolved"

    • setWaitDuration

      public ProcessElement setWaitDuration(Integer waitDuration) throws IllegalStateException
      When waitFor or Process.defaultWaitFor are set to "duration", how long should the wait be before starting the task? If not specified, Process.defaultWaitDuration is used.
      Parameters:
      waitDuration - New waitDuration value. Default value is null
      Returns:
      ProcessElement instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getWaitDuration

      public Integer getWaitDuration()
      When waitFor or Process.defaultWaitFor are set to "duration", how long should the wait be before starting the task? If not specified, Process.defaultWaitDuration is used.
      Returns:
      Current waitDuration value. Default value is null

    • setWaitFor

      public ProcessElement setWaitFor(WaitForType waitFor) throws IllegalStateException
      Condition to wait for before this task is executed. If not specified, the containing Process defaultWaitFor is used.

      When set to "duration" the delay time is set by waitDuration or Process.defaultWaitDuration. For a value of "locator" the locator for which to wait is set by waitLocator.

      Since this waitFor overrides the Process.defaultWaitFor if the latter is set to "systemDone" and a task overrides it with waitFor "locator", be aware that the default "systemDone" is not performed. To apply both, as might be desired, use waitFor "locatorAndSystemDone".

      Parameters:
      waitFor - New waitFor value. Default value is null
      Returns:
      ProcessElement instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getWaitFor

      public WaitForType getWaitFor()
      Condition to wait for before this task is executed. If not specified, the containing Process defaultWaitFor is used.

      When set to "duration" the delay time is set by waitDuration or Process.defaultWaitDuration. For a value of "locator" the locator for which to wait is set by waitLocator.

      Since this waitFor overrides the Process.defaultWaitFor if the latter is set to "systemDone" and a task overrides it with waitFor "locator", be aware that the default "systemDone" is not performed. To apply both, as might be desired, use waitFor "locatorAndSystemDone".

      Returns:
      Current waitFor value. Default value is null

    • setWaitLocator

      public ProcessElement setWaitLocator(String waitLocator) throws IllegalStateException
      Component specified as an AutoTestLocator that should be waited on if waitFor is "locator" or "locatorAndSystemDone".
      Parameters:
      waitLocator - New waitLocator value. Default value is null
      Returns:
      ProcessElement instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created
      See Also:

    • getWaitLocator

      public String getWaitLocator()
      Component specified as an AutoTestLocator that should be waited on if waitFor is "locator" or "locatorAndSystemDone".
      Returns:
      Current waitLocator value. Default value is null
      See Also:

    • completeElement

      public void completeElement(Process process)
      StringMethod called when a processElement completes. Typically used to clear transient state applied to the task while running like forceSingle so it can be executed again later. See also reset().
      Parameters:
      process - the containing process

    • executeElement

      public Boolean executeElement(Process process)
      Method called by Process to have the processElement perform its work. There is no default implementation by ProcessElement, however, all of the system-provided subclasses do implement this method. An implementation or override of this method is one possible customization point. Some classes like ScriptTask perform other means to add customization. For ScriptTask, custom code is expected to handle the ScriptTask.execute() method instead.

      Any implementation of this method must return true if all the work this element needed to perform was completed. Return false if additional work is being performed asynchronously and the process should be paused until element restarts it. Once asynchronous work is complete the task must call Process.start() to restart the workflow with the next task.

      Parameters:
      process - the process that is handling the workflow
      Returns:
      return true if all the work this element needed to perform was completed. Return false if additional work is being performed asynchronously and the process should be paused until element restarts it.

    • getComponentReferences

      public String[] getComponentReferences()
      Returns a list of unique global IDs that are referenced by this task.

      The default implementation returns nothing. Subclasses that add new potential component references should override this method calling this.Super("getComponentReferences", arguments); to allow superclasses to include references first. New references can then be added after checking that the referenced component ID is not already in the list.

      Returns:
      array of component IDs that are referenced by this task

    • getDynamicValue

      public String getDynamicValue(String value, Process process)
      Resolves a dynamic value as taskInputExpressions or returns the value as-is.
      Parameters:
      value - the value to resolve
      process - the current process
      Returns:
      the resolved value

    • getElementDescription

      public String getElementDescription()
      Returns a text description of the element derived from the configuration.

      If no override is provided by the concrete ProcessElement implementation the description is returned.

      Returns:
      the derived element description

    • getInvalidTaskMessage

      public String getInvalidTaskMessage(Process process)
      If this processElement is not valid, returns the message detailing the problem. If there are multiple validation issues, the message may contain a message for each separated by a newline.
      Parameters:
      process - the process that is handling the workflow
      Returns:
      the reason for task being invalid or null if valid

    • getTextFormulaValue

      public String getTextFormulaValue(UserSummary textFormula, Process process)
      Resolves a UserSummary value against the current rule context.
      Parameters:
      textFormula - the UserSummary value to resolve
      process - the current process
      Returns:
      the resolved value

    • isValid

      public Boolean isValid(Process process)
      Is this processElement valid for execution? Called by Process to check the validity of the task before executing it (executeElement()).

      Each task type is responsible for overriding this method to check the various properties that are required for execution.

      When invalid, call getInvalidTaskMessage() to get a message detailing the problem.

      Default implementation calls getInvalidTaskMessage() and return true if the message is null.

      Parameters:
      process - the process that is handling the workflow
      Returns:
      true if task is valid

    • objectReferencesLastTaskOutput

      public Boolean objectReferencesLastTaskOutput(Map object, Process process)
      Does the object have fields that reference the last task output (i.e. $last)?
      Parameters:
      object - object to be checked
      process - the enclosing process
      Returns:
      true if any field in the object references $last

    • reset

      public void reset()
      StringMethod called during Process.reset() giving the task a chance to reset any internal state so it can be executed later. See also completeElement().

    • updateGlobalIDInCriteria

      public Boolean updateGlobalIDInCriteria(AdvancedCriteria criteria, String oldId, String newId)
      Updates AdvancedCriteria Criterion TaskInputExpression values containing ruleScope references.

      This method is a helper to implement task-specific updateGlobalIDReferences().

      Parameters:
      criteria - the criteria to be updated in place
      oldId - the ID being renamed. See Identifier
      newId - the new ID to be assigned. See Identifier
      Returns:
      true if any references were updated; false otherwise

    • updateGlobalIDInTextFormula

      public Boolean updateGlobalIDInTextFormula(UserSummary textFormula, String oldId, String newId)
      Updates text formula containing ruleScope references.

      This method is a helper to implement task-specific updateGlobalIDReferences().

      Parameters:
      textFormula - the UserSummary to be updated in place
      oldId - the ID being renamed. See Identifier
      newId - the new ID to be assigned. See Identifier
      Returns:
      true if any references were updated; false otherwise

    • updateGlobalIDInValueProperty

      public Boolean updateGlobalIDInValueProperty(String propertyName, String oldId, String newId)
      Updates a TaskInputExpression property value containing ruleScope references.

      This method is a helper to implement task-specific updateGlobalIDReferences().

      Parameters:
      propertyName - the property name to be updated in this task
      oldId - the ID being renamed. See Identifier
      newId - the new ID to be assigned. See Identifier
      Returns:
      true if any references were updated; false otherwise

    • updateGlobalIDInValues

      public Boolean updateGlobalIDInValues(Map values, String oldId, String newId)
      Updates a set of TaskInputExpression values containing ruleScope references.

      This method is a helper to implement task-specific updateGlobalIDReferences().

      Parameters:
      values - the object to be updated
      oldId - the ID being renamed. See Identifier
      newId - the new ID to be assigned. See Identifier
      Returns:
      true if any references were updated; false otherwise

    • updateGlobalIDReferences

      public Boolean updateGlobalIDReferences(String oldId, String newId)
      Updates references to a global ID within the properties of this process element (i.e. rename). This method is not called as part of workflow execution but is used by Reify to keep workflow event handlers in sync with ID changes within the screen.

      Each processElement or Task that has properties that save global IDs (like a component ID or criteria referencing ruleContext) must be able to update its references on demand by overriding this method or defer to its superclass.

      There are a number of helper methods to make this easier listed below.

      Parameters:
      oldId - the ID being renamed. See Identifier
      newId - the new ID to be assigned. See Identifier
      Returns:
      true if any references were updated; false otherwise
      See Also:

    • updateLastElementBindingReferences

      public Boolean updateLastElementBindingReferences(String oldId, String newId)
      Update references to a binding $last within properties of this processElement. This method is not called as part of workflow execution but is used by the com.smartgwt.client.tools.WorkflowEditor to adjust last task references as new tasks are inserted.

      Each processElement or Task that has properties supporting taskInputExpressions using the $last syntax must be able to update its references on demand by overriding this method or defer to its superclass.

      There are a number of helper methods to make this easier listed below.

      Parameters:
      oldId - the ID being renamed. See Identifier
      newId - the new ID to be assigned. See Identifier
      Returns:
      true if any references were updated; false otherwise
      See Also:

    • updateLastElementInCriteria

      public Boolean updateLastElementInCriteria(AdvancedCriteria criteria, String taskType)
      Updates AdvancedCriteria Criterion TaskInputExpression values containing $last references. Any implicit reference to the last task is updated to reference a last task of a specified taskType.

      For example, a value of "$last.sequenceNo" would be replaced with "$last[fetch].sequenceNo" if the taskType is "fetch". Existing "$last[...]" references are left as-is.

      This method is a helper to implement task-specific updateLastElementBindingReferences().

      Parameters:
      criteria - the criteria to be updated in place
      taskType - the taskType to be used in new reference
      Returns:
      true if any references were update; false otherwise

    • updateLastElementInValueProperty

      public Boolean updateLastElementInValueProperty(String propertyName, String taskType)
      Updates a TaskInputExpression property value containing $last references. Any implicit reference to the last task is updated to reference a last task of a specified taskType.

      For example, a value of "$last.sequenceNo" would be replaced with "$last[fetch].sequenceNo" if the taskType is "fetch". Existing "$last[...]" references are left as-is.

      This method is a helper to implement task-specific updateLastElementBindingReferences().

      Parameters:
      propertyName - the property name to be updated in this task
      taskType - the taskType to be used in new reference
      Returns:
      true if any references were update; false otherwise

    • updateLastElementInValues

      public Boolean updateLastElementInValues(Map values, String taskType)
      Updates a set of TaskInputExpression values containing $last references. Any implicit reference to the last task is updated to reference a last task of a specified taskType.

      For example, a value of "$last.sequenceNo" would be replaced with "$last[fetch].sequenceNo" if the taskType is "fetch". Existing "$last[...]" references are left as-is.

      This method is a helper to implement task-specific updateLastElementBindingReferences().

      Parameters:
      values - the object to be updated
      taskType - the taskType to be used in new reference
      Returns:
      true if any references were update; false otherwise

    • onInit

      protected void onInit()
      Overrides:
      onInit in class BaseClass

    • setAttribute

      public ProcessElement setAttribute(String attribute, ProcessElement[] value, boolean allowPostCreate)

    • getProcessElements

      public ProcessElement[] getProcessElements(String attribute)

    • convertToJavaScriptArray

      public static JavaScriptObject convertToJavaScriptArray(ProcessElement[] array)