Package com.smartgwt.client.util.workflow

Class Process

java.lang.Object
com.smartgwt.client.core.BaseClass
com.smartgwt.client.util.workflow.Process
All Implemented Interfaces:
HasHandlers, HasFinishedHandlers, HasTraceElementHandlers
Direct Known Subclasses:
Tour
public class Process extends BaseClass implements HasFinishedHandlers, HasTraceElementHandlers
A instance of Process represents a stateful process executing a series of Tasks, which may be:
  • user interactions
  • calls to DataSources (hence: any database or web service)
  • arbitrary code
  • other Processes
A Process is stateful in the sense that it maintains state across the different tasks that are executed. This allows you to maintain context as you walk a user through a multi-step business process in your application, which may involve multiple operations on multiple entities. Each Task that executes can use the Process state as inputs, and can output a result which is stored in the Process state - see TaskIO.

A Process can have multiple branches, choosing the next Task to execute based on Criteria - see DecisionTask and MultiDecisionTask.

Because a Process may return to a previous Task in various situations, the data model of a Process is strictly speaking a graph (a set of nodes connected by arbitary interlinks). However, most processes have sequences of several tasks in a row, and the definition format allows these to be represented as simple Arrays called "sequences", specified via sequences. This reduces the need to manually specify IDs and interlinks for Tasks that simply proceed to the next task in a sequence.

Processes follow all the standard rules for encoding as ComponentXML, however, note that the <Process> tag allows any kind of ProcessElement (tasks, decisions and sequences) to appear as a direct subelement of the <Process> tag without the need for an intervening <elements> or <sequences> tag. The example below demonstrates this shorthand format. 

  <Process ID="processId">
      <ServiceTask ID="serviceTaskId" nextElement="sequenceId" ..>
          <inputFieldList>
              <value>order.countryName</value>
          </inputFieldList>
          <outputFieldList>
              <value>order.countryName</value>
              <value>order.continent</value>
          <outputFieldList>
      </ServiceTask>
      <sequence ID="sequenceId" >
          <StateTask ../>
          <StateTask ../>
          <StateTask ../>
          <StateTask nextElement="userTaskId" ../>
      </sequence>
      <UserTask ID="userTaskId" ../>
      ...
  </Process>
NOTE: you must load the standard DataBinding module before you can use Process.

  • Constructor Details

  • Method Details

    • getOrCreateRef

      public static Process 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

    • setContainerId

      public Process setContainerId(String containerId)
      Identifier of canvas where UI elements created by using inline view property should be added using addMember.
      Parameters:
      containerId - New containerId value. Default value is null
      Returns:
      Process instance, for chaining setter calls
      See Also:

    • getContainerId

      public String getContainerId()
      Identifier of canvas where UI elements created by using inline view property should be added using addMember.
      Returns:
      Current containerId value. Default value is null
      See Also:

    • setDefaultWaitDuration

      public Process setDefaultWaitDuration(Integer defaultWaitDuration) throws IllegalStateException
      When defaultWaitFor or task waitFor are set to "duration", how long should the wait be before starting the task? A task can override the default value with task waitDuration.
      Parameters:
      defaultWaitDuration - New defaultWaitDuration value. Default value is "300"
      Returns:
      Process instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getDefaultWaitDuration

      public Integer getDefaultWaitDuration()
      When defaultWaitFor or task waitFor are set to "duration", how long should the wait be before starting the task? A task can override the default value with task waitDuration.
      Returns:
      Current defaultWaitDuration value. Default value is "300"

    • setDefaultWaitFor

      public Process setDefaultWaitFor(WaitForType defaultWaitFor) throws IllegalStateException
      Condition to wait for before each task is executed. Task waitFor can be specified for individual tasks to override this default.

      For a value of "duration", the delay time is set by defaultWaitDuration and can be overridden by a task waitDuration.

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

      A defaultWaitFor value of "locator" or "locatorAndSystemDone" is not valid.

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

    • getDefaultWaitFor

      public WaitForType getDefaultWaitFor()
      Condition to wait for before each task is executed. Task waitFor can be specified for individual tasks to override this default.

      For a value of "duration", the delay time is set by defaultWaitDuration and can be overridden by a task waitDuration.

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

      A defaultWaitFor value of "locator" or "locatorAndSystemDone" is not valid.

      Returns:
      Current defaultWaitFor value. Default value is null

    • setElements

      public Process setElements(ProcessElement... elements) throws IllegalStateException
      Elements involved in this Process. You can also group elements into sequences to reduce the need to explicitly define IDs for elements and interlink them.
      Parameters:
      elements - New elements value. Default value is null
      Returns:
      Process instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • setMockMode

      public Process setMockMode(Boolean mockMode)
      Enable mock mode on the workflow? By default, this setting does nothing but is available for individual tasks to trigger special action. For example, a task that would normally fail outside of its target environment can take an alternative action during testing.

      mockMode can also be enabled or disabled for an individual task with ProcessElement.mockMode.

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

    • getMockMode

      public Boolean getMockMode()
      Enable mock mode on the workflow? By default, this setting does nothing but is available for individual tasks to trigger special action. For example, a task that would normally fail outside of its target environment can take an alternative action during testing.

      mockMode can also be enabled or disabled for an individual task with ProcessElement.mockMode.

      Returns:
      Current mockMode value. Default value is null

    • setRuleScope

      public Process setRuleScope(String ruleScope) throws IllegalStateException
      Canvas.ID of the component that manages "rule context" for which this process participates. The rule context can be used in taskInputExpression.
      Overrides:
      setRuleScope in class BaseClass
      Parameters:
      ruleScope - New ruleScope value. Default value is null
      Returns:
      Process instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created
      See Also:

    • getRuleScope

      public String getRuleScope()
      Canvas.ID of the component that manages "rule context" for which this process participates. The rule context can be used in taskInputExpression.
      Overrides:
      getRuleScope in class BaseClass
      Returns:
      Current ruleScope value. Default value is null
      See Also:

    • setSequences

      public Process setSequences(ProcessSequence... sequences) throws IllegalStateException
      Sequences of ProcessElements. By defining a sequences of elements you can make the ProcessElement.nextElement implicit.

      Example of using sequences: 

        Process process = new Process();
  process.setStartElement("firstSequence");
  ProcessSequence innerSequence = new ProcessSequence(incTask, add2Task, incTask);
  process.setSequences(
      new ProcessSequence("firstSequence", serviceTask, multiDecisionTask),
      new ProcessSequence("errorFlow", failureTask, userNotifyTask)
  );
  // standalone process elements not part of sequences
  process.setElements(new ServiceTask(){...});
  Record state = new Record();
  state.setAttribute("someField", "someValue");
  process.setState(state);
  process.start();
      Parameters:
      sequences - New sequences value. Default value is null
      Returns:
      Process instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getSequences

      public ProcessSequence[] getSequences()
      Sequences of ProcessElements. By defining a sequences of elements you can make the ProcessElement.nextElement implicit.

      Example of using sequences: 

        Process process = new Process();
  process.setStartElement("firstSequence");
  ProcessSequence innerSequence = new ProcessSequence(incTask, add2Task, incTask);
  process.setSequences(
      new ProcessSequence("firstSequence", serviceTask, multiDecisionTask),
      new ProcessSequence("errorFlow", failureTask, userNotifyTask)
  );
  // standalone process elements not part of sequences
  process.setElements(new ServiceTask(){...});
  Record state = new Record();
  state.setAttribute("someField", "someValue");
  process.setState(state);
  process.start();
      Returns:
      Current sequences value. Default value is null

    • setStartElement

      public Process setStartElement(String startElement) throws IllegalStateException
      The ID of either a sequence or an element which should be the starting point of the process. If not specified, the first sequence is chosen, or if there are no sequences, the first element. - log a warning and do nothing if there are neither sequences or elements
      Parameters:
      startElement - New startElement value. Default value is null
      Returns:
      Process instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getStartElement

      public String getStartElement()
      The ID of either a sequence or an element which should be the starting point of the process. If not specified, the first sequence is chosen, or if there are no sequences, the first element. - log a warning and do nothing if there are neither sequences or elements
      Returns:
      Current startElement value. Default value is null

    • setState

      public Process setState(Record state)
      Current state of a process. As with Records in general, any field of a Record may contain a nested Record or Array of Records, so the process state is essentially a hierarchical data structure.

      Transient state

      In addition to the explicit process state there is a "transient state." The transient state represents the complete output of each of the last tasks of each type within the current process execution. This allows easy reference to the previous task output with taskInputExpressions.

      If this method is called after the component has been drawn/initialized: Set process state for current process
      Parameters:
      state - the new process state. Default value is null
      Returns:
      Process instance, for chaining setter calls

    • getState

      public Record getState()
      Current state of a process. As with Records in general, any field of a Record may contain a nested Record or Array of Records, so the process state is essentially a hierarchical data structure.

      Transient state

      In addition to the explicit process state there is a "transient state." The transient state represents the complete output of each of the last tasks of each type within the current process execution. This allows easy reference to the previous task output with taskInputExpressions.
      Returns:
      Current state value. Default value is null

    • setTraceContext

      public Process setTraceContext(Map traceContext)
      Context object to be passed to Process.traceElement() during process execution.

      Note : This is an advanced setting

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

    • getTraceContext

      public Map getTraceContext()
      Context object to be passed to Process.traceElement() during process execution.
      Returns:
      Current traceContext value. Default value is null

    • setWizard

      public Process setWizard(Boolean wizard) throws IllegalStateException
      If wizard is set then current workflow will be handled as wizard. Every userTask will hide associated form after user finished step.
      Parameters:
      wizard - New wizard value. Default value is false
      Returns:
      Process instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getWizard

      public Boolean getWizard()
      If wizard is set then current workflow will be handled as wizard. Every userTask will hide associated form after user finished step.
      Returns:
      Current wizard value. Default value is false

    • addFinishedHandler

      public HandlerRegistration addFinishedHandler(FinishedHandler handler)
      Add a finished handler.

      StringMethod called when a process completes, meaning the process executes a ProcessElement with no next element.

      Specified by:
      addFinishedHandler in interface HasFinishedHandlers
      Parameters:
      handler - the finished handler
      Returns:
      HandlerRegistration used to remove this handler

    • getComponentReferences

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

      List is assembled by calling ProcessElement.getComponentReferences() for each task in the workflow and filtering the list to the unique component IDs.

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

    • getElement

      public ProcessElement getElement(String ID)
      Retrieve a ProcessElement by its ID
      Parameters:
      ID - id of the process element
      Returns:
      the indicated process element, or null if no such element exists

    • getLastTaskOutput

      public Object getLastTaskOutput()
      Returns the task output of the last task executed. More commonly a TaskInputExpression property is used (see ProcessElement.getDynamicValue()).
      Returns:
      the last task output or null if none is found

    • getLastTaskOutput

      public Object getLastTaskOutput(String taskType)
      Returns the task output of the last task executed. More commonly a TaskInputExpression property is used (see ProcessElement.getDynamicValue()).
      Parameters:
      taskType - the optional task type to lookup in last task output
      Returns:
      the last task output or null if none is found

    • getProcessDescription

      public String getProcessDescription()
      Returns the process description as HTML.
      Returns:
      the process description as HTML

    • getStateVariable

      public Object getStateVariable(String stateVariablePath)
      Returns a variable value from the process state. Values can be written into process state by setStateVariable(), setting ProcessElement.bindOutput, or various task output settings (See TaskIO.)
      Parameters:
      stateVariablePath - path to variable in process state to set. segments are separated by a decimal point (.)
      Returns:
      the value found at the path

    • passThruTaskOutput

      public void passThruTaskOutput(ProcessElement task)
      Takes the last task output and sets it as the task output for the task.

      This method is not just a shortcut to set output of a pass-thru task but it also records the correct schema of the passed-thru output so it can be quickly looked up.

      Parameters:
      task - the workflow task setting the output (i.e. this)

    • reset

      public void reset()
      Reset process to its initial state, so process can be started again.

    • reset

      public void reset(Record state)
      Reset process to its initial state, so process can be started again.
      Parameters:
      state - new state of the process

    • setNextElement

      public void setNextElement()
      Sets the task ID of the next task to execute after the current task finishes. If the task is not found or null is passed as the nextElement, the current process will be terminated instead.

    • setNextElement

      public void setNextElement(String nextElement)
      Sets the task ID of the next task to execute after the current task finishes. If the task is not found or null is passed as the nextElement, the current process will be terminated instead.
      Parameters:
      nextElement - ID of the next task execute or null to terminate process

    • setStateVariable

      public void setStateVariable(String stateVariablePath, Object value)
      Sets a process state variable for later reference with getStateVariable() or more commonly with a TaskInputExpression property.
      Parameters:
      stateVariablePath - path to variable in process state to set. segments are separated by a decimal point (.)
      value - the value to save

    • setTaskOutput

      public void setTaskOutput(ProcessElement task, Object value)
      Sets the task output of task in the process state so it can be used by later tasks with getLastTaskOutput() or more commonly with a TaskInputExpression property.

      If the task sets bindOutput the output value is also written into that process state variable.

      Parameters:
      task - the workflow task setting the output (i.e. this)
      value - the output value for task

    • start

      public void start()
      Starts this task by executing the startElement. Also used by asynchronous tasks to restart the workflow.

    • addTraceElementHandler

      public HandlerRegistration addTraceElementHandler(TraceElementHandler handler)
      Add a traceElement handler.

      StringMethod called during process execution before each task element is processed.

      Specified by:
      addTraceElementHandler in interface HasTraceElementHandlers
      Parameters:
      handler - the traceElement handler
      Returns:
      HandlerRegistration used to remove this handler

    • getProcess

      public static Process getProcess(String processId)
      Get a Process instance by its ID.

      Each process instance created that has an ID is cached for later lookup by that ID. If two processes have the same ID the last one is cached, overwriting the first. Note that the process instances are not affected - only the cache reference.

      Parameters:
      processId - process ID to retrieve. See Identifier
      Returns:
      the process, or null if not found
      See Also:

    • onInit

      protected void onInit()
      Overrides:
      onInit in class BaseClass

    • setAttribute

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

    • setConfig

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

    • loadProcess

      public static void loadProcess(String processId, ProcessCallback callback)

    • getProcessElements

      public ProcessElement[] getProcessElements(String attribute)

    • getElements

      public ProcessElement[] getElements()
      Elements involved in this Process. You can also group elements into sequences to reduce the need to explicitly define IDs for elements and interlink them.
      Returns:
      ProcessElement

    • setStartElement

      public void setStartElement(ProcessElement startElement) throws IllegalStateException
      Throws:
      IllegalStateException
      See Also: