Package org.imixs.workflow.engine

Class WorkflowService

java.lang.Object
org.imixs.workflow.engine.WorkflowService
All Implemented Interfaces:
WorkflowContext
@DeclareRoles({"org.imixs.ACCESSLEVEL.NOACCESS","org.imixs.ACCESSLEVEL.READERACCESS","org.imixs.ACCESSLEVEL.AUTHORACCESS","org.imixs.ACCESSLEVEL.EDITORACCESS","org.imixs.ACCESSLEVEL.MANAGERACCESS"}) @RolesAllowed({"org.imixs.ACCESSLEVEL.NOACCESS","org.imixs.ACCESSLEVEL.READERACCESS","org.imixs.ACCESSLEVEL.AUTHORACCESS","org.imixs.ACCESSLEVEL.EDITORACCESS","org.imixs.ACCESSLEVEL.MANAGERACCESS"}) public class WorkflowService extends Object implements WorkflowContext
The WorkflowService is the Java EE Implementation for the Imixs Workflow Core API. This interface acts as a service facade and supports basic methods to create, process and access workitems. The Interface extends the core api interface org.imixs.workflow.WorkflowManager with getter methods to fetch collections of workitems.
Author:
rsoika

  • Field Details

  • Constructor Details

    • WorkflowService

      public WorkflowService()

  • Method Details

    • getWorkItem

      public ItemCollection getWorkItem(String uniqueid)
      This method loads a Workitem with the corresponding uniqueid.
      Specified by:
      getWorkItem in interface WorkflowContext

    • getWorkListByOwner

      public List<ItemCollection> getWorkListByOwner(String name, String type, int pageSize, int pageIndex, String sortBy, boolean sortReverse)
      Returns a collection of workitems containing a '$owner' item belonging to a specified username. The '$owner' item can be controlled by the plug-in org.imixs.workflow.plugins.OwnerPlugin
      Parameters:
      name - = username for itme '$owner' - if null current username will be used
      pageSize - = optional page count (default 20)
      pageIndex - = optional start position
      type - = defines the type property of the workitems to be returnd. can be null
      sortBy - -optional field to sort the result
      sortReverse - - optional sort direction
      Returns:
      List of workitems

    • getWorkListByAuthor

      public List<ItemCollection> getWorkListByAuthor(String name, String type, int pageSize, int pageIndex, String sortBy, boolean sortReverse)
      Returns a collection of workitems for which the specified user has explicit write permission. The name is a username or role contained in the $WriteAccess attribute of the workItem. The method returns only workitems the call has sufficient read access for.
      Parameters:
      name - = username or role contained in $writeAccess - if null current username will be used
      pageSize - = optional page count (default 20)
      pageIndex - = optional start position
      type - = defines the type property of the workitems to be returned. can be null
      sortBy - -optional field to sort the result
      sortReverse - - optional sort direction
      Returns:
      List of workitems

    • getWorkListByCreator

      public List<ItemCollection> getWorkListByCreator(String name, String type, int pageSize, int pageIndex, String sortBy, boolean sortReverse)
      Returns a collection of workitems created by a specified user ($Creator). The behaivor is simmilar to the method getWorkList.
      Parameters:
      name - = username for property $Creator - if null current username will be used
      pageSize - = optional page count (default 20)
      pageIndex - = optional start position
      type - = defines the type property of the workitems to be returnd. can be null
      sortBy - -optional field to sort the result
      sortReverse - - optional sort direction
      Returns:
      List of workitems

    • getWorkListByWriteAccess

      public List<ItemCollection> getWorkListByWriteAccess(String type, int pageSize, int pageIndex, String sortBy, boolean sortReverse)
      Returns a collection of workitems where the current user has a writeAccess. This means that at least one of the userNames is contained in the $writeaccess property.
      Parameters:
      pageSize - = optional page count (default 20)
      pageIndex - = optional start position
      type - = defines the type property of the workitems to be returnd. can be null
      sortorder - = defines sortorder (SORT_ORDER_CREATED_DESC = 0 SORT_ORDER_CREATED_ASC = 1 SORT_ORDER_MODIFIED_DESC = 2 SORT_ORDER_MODIFIED_ASC = 3)
      sortBy - -optional field to sort the result
      sortReverse - - optional sort direction
      Returns:
      List of workitems

    • getWorkListByGroup

      public List<ItemCollection> getWorkListByGroup(String name, String type, int pageSize, int pageIndex, String sortBy, boolean sortReverse)
      Returns a list of workitems filtered by the field $workflowgroup the method supports still also the deprecated field "txtworkflowgroup"
      Parameters:
      name -
      type -
      pageSize - = optional page count (default 20)
      pageIndex - = optional start position
      sortBy - -optional field to sort the result
      sortReverse - - optional sort direction
      Returns:

    • getWorkListByProcessID

      public List<ItemCollection> getWorkListByProcessID(int aid, String type, int pageSize, int pageIndex, String sortBy, boolean sortReverse)
      Returns a collection of workitems belonging to a specified $taskID defined by the workflow model. The behaivor is simmilar to the method getWorkList.
      Parameters:
      aID - = $taskID for the workitems to be returned.
      pageSize - = optional page count (default 20)
      pageIndex - = optional start position
      type - = defines the type property of the workitems to be returnd. can be null
      sortBy - -optional field to sort the result
      sortReverse - - optional sort direction
      Returns:
      List of workitems

    • getWorkListByRef

      public List<ItemCollection> getWorkListByRef(String aref, String type, int pageSize, int pageIndex, String sortBy, boolean sortReverse)
      Returns a collection of workitems belonging to a specified workitem identified by the attribute $UniqueIDRef. The behaivor of this Mehtod is simmilar to the method getWorkList.
      Parameters:
      aref - A unique reference to another workitem inside a database *
      pageSize - = optional page count (default 20)
      pageIndex - = optional start position
      type - = defines the type property of the workitems to be returnd. can be null
      sortBy - -optional field to sort the result
      sortReverse - - optional sort direction
      Returns:
      List of workitems

    • getWorkListByRef

      public List<ItemCollection> getWorkListByRef(String aref)
      Returns a collection of all workitems belonging to a specified workitem identified by the attribute $UniqueIDRef.
      Returns:
      List of workitems

    • processWorkItem

      public ItemCollection processWorkItem(ItemCollection workitem) throws AccessDeniedException, ProcessingErrorException, PluginException, ModelException
      This method processes a workItem by the WorkflowKernel and saves the workitem after the processing was finished successful. The workitem have to provide at least the properties '$modelversion', '$taskid' and '$eventid'

      Before the method starts processing the workitem, the method load the current instance of the given workitem and compares the property $taskID. If it is not equal the method throws an ProcessingErrorException.

      After the workitem was processed successful, the method verifies the property $workitemList. If this property holds a list of entities these entities will be saved and the property will be removed automatically.

      The method provides a observer pattern for plugins to get called during the processing phase.

      Specified by:
      processWorkItem in interface WorkflowContext
      Parameters:
      workitem - - the workItem to be processed
      Returns:
      updated version of the processed workItem
      Throws:
      AccessDeniedException - - thrown if the user has insufficient access to update the workItem
      ProcessingErrorException - - thrown if the workitem could not be processed by the workflowKernel
      PluginException - - thrown if processing by a plugin fails
      ModelException

    • processWorkItem

      public ItemCollection processWorkItem(ItemCollection workitem, ItemCollection event) throws AccessDeniedException, ProcessingErrorException, PluginException, ModelException
      This method processes a workItem based on a given event.
      Parameters:
      workitem - - the workItem to be processed
      event - - event object
      Returns:
      updated version of the processed workItem
      Throws:
      AccessDeniedException - - thrown if the user has insufficient access to update the workItem
      ProcessingErrorException - - thrown if the workitem could not be processed by the workflowKernel
      PluginException - - thrown if processing by a plugin fails
      ModelException
      See Also:
      • ItemCollection processWorkItem(ItemCollection workitem)

    • processWorkItem

      public ItemCollection processWorkItem(ItemCollection workitem, int eventID) throws AccessDeniedException, ProcessingErrorException, PluginException, ModelException
      This method processes a workItem based on a given event.
      Parameters:
      workitem - - the workItem to be processed
      event - - event object
      Returns:
      updated version of the processed workItem
      Throws:
      AccessDeniedException - - thrown if the user has insufficient access to update the workItem
      ProcessingErrorException - - thrown if the workitem could not be processed by the workflowKernel
      PluginException - - thrown if processing by a plugin fails
      ModelException
      See Also:
      • ItemCollection processWorkItem(ItemCollection workitem)

    • processWorkItemByNewTransaction

      public ItemCollection processWorkItemByNewTransaction(ItemCollection workitem) throws AccessDeniedException, ProcessingErrorException, PluginException, ModelException
      This method processes a workitem in a new transaction.
      Throws:
      ModelException
      PluginException
      ProcessingErrorException
      AccessDeniedException

    • removeWorkItem

      public void removeWorkItem(ItemCollection aworkitem) throws AccessDeniedException
      Throws:
      AccessDeniedException

    • getSessionContext

      public jakarta.ejb.SessionContext getSessionContext()
      Returns an instance of the EJB session context.
      Returns:

    • getDocumentService

      public DocumentService getDocumentService()
      Returns an instance of the DocumentService EJB.
      Returns:

    • getReportService

      public ReportService getReportService()
      Returns an instance of the ReportService EJB.
      Returns:

    • registerPlugins

      protected void registerPlugins(WorkflowKernel workflowkernel, ItemCollection profile) throws PluginException, ModelException
      This method register all plugin classes listed in the model profile
      Throws:
      PluginException
      ModelException

    • registerAdapters

      protected void registerAdapters(WorkflowKernel workflowkernel)

    • updateMetadata

      protected void updateMetadata(ItemCollection workitem)
      This method updates the workitem metadata. The following items will be updated:
      • $creator
      • $editor
      • $lasteditor
      • $participants

      The method also migrates deprected items.

      Parameters:
      workitem -

    • findPluginByName

      protected Plugin findPluginByName(String pluginClassName)
      This method returns an injected Plugin by name or null if no plugin with the requested class name is injected.
      Parameters:
      pluginClassName -
      Returns:
      plugin class or null if not found

    • fetchModel

      public org.openbpmn.bpmn.BPMNModel fetchModel(String version) throws ModelException
      This method returns a exclusive thread save BPMNModel instance. The method must not return a shared model instance. The method must throw a ModelException in case no model matching the requested version exists. A client can call findModelVersionByWorkitem to resolve a valid model version for a workitem.
      Specified by:
      fetchModel in interface WorkflowContext
      Parameters:
      version - - valid model version
      Returns:
      an instance of a BPMNModel to be used in a thread save way
      Throws:
      ModelException

    • findModelVersionByWorkitem

      public String findModelVersionByWorkitem(ItemCollection workitem) throws ModelException
      Returns a Model matching the $modelversion of a given workitem. The $modelversion can optional be provided as a regular expression.

      In case no matching model version exits, the method tries to find the highest Model Version matching the corresponding workflow group.

      The method throws a ModelException in case the model version did not exits.

      Specified by:
      findModelVersionByWorkitem in interface WorkflowContext
      Returns:
      version matching the params of the given workitem
      Throws:
      ModelException

    • findModelVersionByRegEx

      public String findModelVersionByRegEx(String modelRegex)
      This method returns a sorted list of model versions matching a given regex for a model version. The result is sorted in reverse order, so the highest version number is the first in the result list.
      Specified by:
      findModelVersionByRegEx in interface WorkflowContext
      Parameters:
      group -
      Returns:

    • findModelVersionByGroup

      public String findModelVersionByGroup(String group) throws ModelException
      Returns a version by Group. The method computes a sorted list of all model versions containing the requested workflow group. The result is sorted in reverse order, so the highest version number is the first in the result list.
      Specified by:
      findModelVersionByGroup in interface WorkflowContext
      Parameters:
      group - - name of the workflow group
      Returns:
      list of matching model versions
      Throws:
      ModelException

    • getEvents

      public List<ItemCollection> getEvents(ItemCollection workitem) throws ModelException
      This returns a list of workflow events assigned to a given workitem. The method evaluates the events for the current $modelversion and $taskid. The result list is filtered by the properties 'keypublicresult' and 'keyRestrictedVisibility'.

      If the property keyRestrictedVisibility exits the method test if the current username is listed in one of the namefields.

      If the current user is in the role 'org.imixs.ACCESSLEVEL.MANAGERACCESS' the property keyRestrictedVisibility will be ignored.

      If the model version does not exist the model is resolved by regular expressions using the method findModelByWorkitem

      If not model can be found or the $taskID is not defined by the model a ModelException is thrown.

      Parameters:
      workitem -
      Returns:
      Throws:
      ModelException - if model is not found or task is not defined by the given model

    • getUserName

      public String getUserName()
      Obtain the java.security.Principal that identifies the caller and returns the name of this principal.
      Returns:
      the user name

    • isUserInRole

      public boolean isUserInRole(String rolename)
      Test if the caller has a given security role.
      Parameters:
      rolename -
      Returns:
      true if user is in role

    • getUserNameList

      public List<String> getUserNameList()
      This method returns a list of user names, roles and application groups the caller belongs to.
      Returns:

    • evalNextTask

      public ItemCollection evalNextTask(ItemCollection workitem) throws PluginException, ModelException
      The method evaluates the next task for a process instance (workitem) based on the current model definition. A Workitem must at least provide the properties $TASKID and $EVENTID.

      During the evaluation life-cycle more than one events can be evaluated. This depends on the model definition which can define follow-up-events, split-events and conditional events.

      The method did not persist the process instance or execute any plugin or adapter classes.

      Specified by:
      evalNextTask in interface WorkflowContext
      Returns:
      Task entity
      Throws:
      PluginException
      ModelException

    • adaptText

      public String adaptText(String text, ItemCollection documentContext) throws PluginException
      The method adaptText can be called to replace predefined xml tags included in a text with custom values. The method fires a CDI event to inform TextAdapterServices to parse and adapt a given text fragment.
      Parameters:
      text -
      documentContext -
      Returns:
      Throws:
      PluginException

    • adaptTextList

      public List<String> adaptTextList(String text, ItemCollection documentContext) throws PluginException
      The method adaptTextList can be called to replace a text with custom values. The method fires a CDI event to inform TextAdapterServices to parse and adapt a given text fragment. The method expects a textList result.
      Parameters:
      text -
      documentContext -
      Returns:
      Throws:
      PluginException

    • evalWorkflowResult

      public ItemCollection evalWorkflowResult(ItemCollection event, String xmlTag, ItemCollection documentContext, boolean resolveItemValues) throws PluginException
      The method evaluates the WorkflowResult for a given BPMN event and returns a ItemColleciton containing all item values of a specified xml tag. Each tag definition must contain at least a name attribute and may contain an optional list of additional attributes.

      The method generates a item for each content element and attribute value. e.g.:

      <item name="comment" ignore="true">text</item>

      This example will result in an ItemCollection with the attributes 'comment' with value 'text' and 'comment.ignore' with the value 'true'

      Also embedded itemVaues can be resolved (resolveItemValues=true):

      <somedata>ABC<itemvalue>$uniqueid</itemvalue></somedata>

      This example will result in a new item 'somedata' with the $uniqueid prefixed with 'ABC'

      Specified by:
      evalWorkflowResult in interface WorkflowContext
      Parameters:
      event -
      xmlTag - - XML tag to be evaluated
      documentContext -
      resolveItemValues - - if true, itemValue tags will be resolved.
      Returns:
      eval itemCollection or null if no tags are contained in the workflow result.
      Throws:
      PluginException - if the xml structure is invalid

    • evalWorkflowResult

      public ItemCollection evalWorkflowResult(ItemCollection event, String tag, ItemCollection documentContext) throws PluginException
      The method evaluates the WorkflowResult for a given BPMN event and returns a ItemColleciton containing all item values of a specified tag name. Each tag definition of a WorkflowResult contains a name and a optional list of additional attributes. The method generates a item for each content element and attribute value.
      e.g. text
      will result in the attributes 'comment' with value 'text' and 'comment.ignore' with the value 'true'

      Also embedded itemVaues can be resolved (resolveItemValues=true):

      <somedata>ABC<itemvalue>$uniqueid</itemvalue></somedata>

      This example will result in a new item 'somedata' with the $uniqueid prefixed with 'ABC'

      Specified by:
      evalWorkflowResult in interface WorkflowContext
      Parameters:
      event -
      tag - - tag to be evaluated
      documentContext -
      Returns:
      Throws:
      PluginException
      See Also:

    • evalWorkflowResultXML

      public List<ItemCollection> evalWorkflowResultXML(ItemCollection event, String xmlTag, String name, ItemCollection documentContext, boolean resolveItemValues) throws PluginException
      The method evaluates a XML tag from the WorkflowResult for a given BPMN event. The method returns a list of ItemCollecitons matching the given XML tag and name attribtue. A custom XML configuriaton may contain one or many XML tags with the same name. Each result ItemCollection holds the tag values of each XML tag. Example: 
       
 <imixs-config name="CONFIG">
   <textblock>....</textblock>
   <template>....</template>
 </imixs-config>
      Parameters:
      event -
      xmlTag - - xml tag to be evaluated
      name - - value of the matching name attribute
      documentContext -
      resolveItemValues - - if true, itemValue tags will be resolved.
      Returns:
      list of ItemCollections
      Throws:
      PluginException - if the xml structure is invalid