Package com.orchestranetworks.workflow

# Class UserTask

java.lang.Object
com.orchestranetworks.workflow.UserTask

public abstract class UserTask extends Object
If a user task requires custom behavior that cannot be specified declaratively in the workflow model, this abstract class must be extended. This custom behavior can involve the creation of the user task's work items, the checking of the work item's underlying user interaction, or the completion of the user task.

### About work items

The definition and life cycle of work items is detailed in the chapter Work items.

If the user task's state is set to error (see methods below), the administrator must fix the issue, then restart the token.

### Java object life cycle

This class is state-less, it is instantiated before invoking any of its methods below.

See Also:
  - Example of a UserTask

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `UserTask.CompletionStrategy`
  Defines the different strategies for work items completion.
  `static enum`
  `UserTask.UserTaskMode`
  Represents the user task mode.
  `static interface`
  `UserTask.WorkItem`
  Defines the resulting state of a work item.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `UserTask()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `checkBeforeWorkItemCompletion(UserTaskBeforeWorkItemCompletionContext aContext)`
  This method is automatically invoked when the user clicks the 'accept' or the 'reject' button to accept or reject the underlying interaction.
  `List<UserReference>`
  `getUsersForAllocation(UserTaskUsersForAllocationCollectorContext aContext)`
  This method is automatically invoked when a workflow administrator clicks the 'allocate' or 'reallocate' administration action of a work item.
  `void`
  `handleCreate(UserTaskCreationContext aContext)`
  This method is automatically executed when the control flow reaches the user task, for creating and offering (or allocating) work item(s).
  `void`
  `handleWorkItemCompletion(UserTaskWorkItemCompletionContext aContext)`
  This method is automatically invoked at work item completion in order to decide whether the whole user task instance has been completed.

  ### Methods inherited from class java.lang.Object

  `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### UserTask

    public UserTask()

- ## Method Details

  - ### handleCreate

    public void handleCreate(UserTaskCreationContext aContext) throws OperationException
    This method is automatically executed when the control flow reaches the user task, for creating and offering (or allocating) work item(s).

    In the default user task mode (single work items) if this method has not been overridden, its default behavior is to use the properties that are specified under the 'Offered to' node on the task definition. Concretely, when a work item is created:

    - if only one profile is defined and is a user reference, it is directly allocated to the specified user;
    - in other cases, the work item is offered to the defined users, or to the members of the defined roles.

    In the legacy mode (multi work items), if this method has not been overridden, its default behavior is to use the properties that are specified under the 'Profiles' node on the task definition. Concretely, for each specified profile under this node, a work item is created and:

    - if the profile is a role, it is offered to the users who belong to the role;
    - if the profile is a user reference, it is directly allocated to the specified user.
    Throws:
      `OperationException` - if any problem occurs; in this case, the user task is set to an error state.
      `IllegalStateException` -
      - if the user task is not in legacy multi-work items mode, and if the method tries to create several work items. Only one work item can be created with the default single work item mode;
      - if no profile has been defined in the user task definition (at least one profile is required).

  - ### checkBeforeWorkItemCompletion

    public void checkBeforeWorkItemCompletion(UserTaskBeforeWorkItemCompletionContext aContext)
    This method is automatically invoked when the user clicks the 'accept' or the 'reject' button to accept or reject the underlying interaction.

    By default, this method does nothing.

    This method must be overridden when blocking checks are needed before the work item is actually completed.

    Since:
      5.4.3
    See Also:
      - `SessionInteraction`

  - ### handleWorkItemCompletion

    public void handleWorkItemCompletion(UserTaskWorkItemCompletionContext aContext) throws OperationException
    This method is automatically invoked at work item completion in order to decide whether the whole user task instance has been completed. Work item completion occurs when the user has clicked on the 'accept' or 'reject' button, and this action has been `accepted`.

    By default, this method completes the user task. Overriding this method gives the opportunity to write specific values to the process instance context.

    In the legacy user task mode (multi work items), if this method has not been overridden, its default behavior is to use the properties that are specified under the 'Termination' node on the task definition Concretely:

    1. Based on the "Task termination criteria" property, either the task is considered as complete or it waits until another work item is completed. This corresponds to the invocation of the method `UserTaskWorkItemCompletionContext.checkAllWorkItemMatchStrategy()`.
    2. If the number of rejected work items is above the 'Rejection Threshold' property, it throws an `OperationException` (the user task is set to an error state).

    Overriding this method gives the opportunity to write specific values to the process instance context or to refine the completion/rejection criteria.

    Known limitation: the data context of the process instance is only saved at the completion of a user task, namely when the method `completeUserTask` is invoked. The method `DataContext.setVariableString(String, String)` is supposed to write variables to the data context of the process instance. However, in the case of multiple work items for a single user task, only the data context from the last work item to finish is actually written to the process instance context. That is, none of the data context changes from previously finished work items have any effect. Therefore, if incremental changes between work items in the same user task are necessary, the data context changes must be saved in a specific technical table at each work item completion. At the completion of the user task, all these changes must be saved manually to the process instance context.

    Throws:
      `OperationException` - if any problem occurs or if the user task is rejected; in this case, the user task is set to an error state.

  - ### getUsersForAllocation

    public List<UserReference> getUsersForAllocation(UserTaskUsersForAllocationCollectorContext aContext) throws OperationException
    This method is automatically invoked when a workflow administrator clicks the 'allocate' or 'reallocate' administration action of a work item. It returns the list of users to whom the work item may be allocated or reallocated to.

    It is useful to overwrite this method to dynamically build the list of users instead of using the default list.

    Implementation of this method may get the default list by calling `super.getUsersForAllocation(aContext)` and then remove or add users

    If an error occurs in this method, the error reason will be displayed to the user, and the users list will be hidden.

    Throws:
      `OperationException`
    Since:
      5.5.0