User Task State

The User Task State in xFlow is a critical component for integrating human interactions seamlessly into automated workflows. It allows tasks that require human intervention, such as approvals, reviews, or data entry, to be effectively managed within the workflow. This documentation explains the purpose, properties, and various concepts associated with the User Task State, including task assignment, task listeners, task outcomes, task actions, and event chaining.

Purpose of User Task State

The User Task State is designed to manage tasks that require human intervention within an automated workflow. It facilitates the following:

1. Task Assignment and Management: Assigns tasks to specific users or groups, ensuring that the right people are involved in the workflow at the right time.

2. Human Interaction: Captures user inputs, approvals, and decisions, integrating them into the workflow execution.

3. Control Flow: Manages the progression of the workflow based on user actions and decisions, allowing for dynamic and flexible workflow execution.

Properties of User Task State

The User Task State has several properties that define how it operates within a workflow. These properties provide the flexibility needed to tailor the user task to specific requirements. Many of these properties can be set using workflow expressions, allowing for dynamic and context-sensitive configurations.

Task Key

• Name: taskKey

• Type: string

• Description: A unique identifier for the user task within the workflow. It is used to reference the task in the workflow definition and tracking.

• Example:

  taskKey: "approveOrder"

Form Key

• Name: formKey

• Type: string

• Description: Identifies the UI form to be used for the task in the xFlow task handling interface. This key links the workflow to the appropriate form for capturing user input. See User Task Form Support for more details.
• Example:

  formKey: "LCD#65d6aad45a18672fd954d93d"

Assignee

• Name: assignee

• Type: string

• Description: Specifies a single user to whom the task is assigned. This ensures that a specific individual is responsible for completing the task. The value can be set dynamically using workflow expressions.

• Example:

  assignee: "${ .context.managerEmail }"

Candidate Users

• Name: candidateUsers

• Type: array

• Description: A list of users who are eligible to claim and work on the task. This allows for flexibility in task assignment, as any user in the list can take ownership of the task. The value can be set dynamically using workflow expressions.

• Example:

  candidateUsers: ["${ .context.approver1 }", "${ .context.approver2 }"]

Candidate Groups

• Name: candidateGroups

• Type: array

• Description: A list of groups whose members are eligible to claim and work on the task. This enables task assignment to teams or departments, rather than individual users. The value can be set dynamically using workflow expressions.

• Example:

  candidateGroups: ["${ .context.department }"]

Watcher

• Name: watcher

• Type: string

• Description: Specifies a user who can view the task but not act on it. This role is useful for auditors or supervisors who need to monitor task progress without direct involvement. The value can be set dynamically using workflow expressions.

• Example:

  watcher: "${ .context.auditorEmail }"

Task Owner

• Name: taskOwner

• Type: string

• Description: Specifies the owner of the task who has oversight responsibilities. The task owner can reassign the task or make changes to its configuration. The value can be set dynamically using workflow expressions.

• Example:

  taskOwner: "${ .context.supervisorEmail }"

Delegation

• Name: delegation

• Type: object

• Description: Specifies delegation details if the task is delegated to another user. This allows for temporary reassignment of tasks during absences or when additional expertise is required. The values can be set dynamically using workflow expressions.

• Example:

  delegation: 
    delegateTo: "${ .context.delegateEmail }"
    delegateReason: "Temporary assignment due to absence"

Delegation and Task Owner Relationship

Delegating a task involves assigning it to another user temporarily while maintaining overall control with the task owner. When a task is delegated, the assignee is set to the new user, and the delegation state is set to DelegationState.PENDING. If no taskOwner is set on the task, the current assignee becomes the task owner. The new assignee must resolve the task and report back to the owner, who has the authority to complete the task. This ensures that the task owner retains ultimate responsibility and oversight of the task.

Task Assignment

Task assignment in the User Task State is vital for designating responsibility for the task's completion. It is directly influenced by the properties assignee, candidateUsers, and candidateGroups. This model allows for tasks to be assigned either directly to a specific individual or to a pool of eligible candidates.

• Assignee: A specific user designated to perform and complete the task. The task is directly assigned to this user, making them primarily responsible for its execution. The value can be set dynamically using workflow expressions.

  • Example:

    assignee: "${ .context.managerEmail }"

• Candidate Users: A list of users who are eligible to claim the task. This allows for a flexible assignment where any of the listed users can take responsibility for the task. The value can be set dynamically using workflow expressions.

  • Example:

    candidateUsers: ["${ .context.approver1 }", "${ .context.approver2 }"]

• Candidate Groups: Specifies one or more groups whose members are eligible to claim the task. This is particularly useful in scenarios where tasks are suitable for any member of a department or team. The value can be set dynamically using workflow expressions.

  • Example:

    candidateGroups: ["${ .context.department }"]

Task Listeners

Task listeners in xFlow are configured to respond to task lifecycle events, facilitating automated reactions at various stages of a task's lifecycle, including creation, assignment, update, completion, deletion, and timeouts.

Properties of Task Listener

Parameter	Description	Type	Required
taskEvent	Specifies the lifecycle event to monitor.	string	yes
actionMode	Dictates whether actions are executed sequentially or in parallel.	string	no
actions	Actions initiated when the event occurs.	array of Action	yes
eventDataFilter	Filters and maps event data to the actions.	EventDataFilter	no

Events

• created: Triggered when a new task instance is created.

• assigned: Occurs when a task is assigned to a user.

• updated: Fired when any update to the task occurs.

• completed: Triggered when the task is completed by the assignee.

• deleted: Occurs when the task is deleted.

• timeout: Triggered when the task reaches its due date without completion.

Event Chaining

Event chaining allows for a series of actions to be triggered in response to task events. This can be useful for automating processes such as notifications, status updates, and other workflow-related tasks.

The execution of Task Listeners is dependent on the order of firing of the following task-related events:

• create: Fires when the task has been created as a transient object with all task properties. No other task-related event will be fired before the create event. The event allows us to inspect all properties of the task when we receive it in the create listener.

• update: Occurs when a task property (e.g., assignee, owner, priority, etc.) on an already created task is changed. Note that the initialization of a task does not fire an update event (the task is being created). This also means that the update event will always occur after a create event has already occurred.

• assignment: Specifically tracks the changes of the Task's assignee property. The event may be fired on two occasions: When a task with an explicitly defined assignee is created, the assignment event will be fired after the create event. When an already created task is assigned, i.e., the Task's assignee property is changed, the assignment event will follow the update event since changing the assignee property results in an updated task.

• complete: Occurs when the task is successfully completed, resulting in the end of the task event lifecycle.

• delete: Occurs just before the task is deleted. No other event is fired after the delete event since it results in the end of the task event lifecycle. This means that the delete event is mutually exclusive with the complete event.

Example Task Listener

taskListeners:
  - taskEvent: created
    actionMode: sequential
    actions:
      - functionRef:
          refName: NotifyUserTaskCreated
          arguments:
            taskId: '${ .task.id }'

Task Outcomes

Task outcomes define the decision paths available upon task completion, linking user decisions to specific workflow transitions. They play a crucial role in controlling the outgoing flow of the user task and overall workflow execution. Task outcomes are displayed in the xFlow task handling UI form as buttons, allowing users to select an outcome and provide the necessary data input.

Properties of Task Outcome

Parameter	Description	Type	Required
code	Unique identifier for the outcome.	string	yes
name	Descriptive name of the outcome.	string	yes
outcomeDecision	Decision resulting from this outcome.	string	yes
formKey	Specifies the form used for data collection.	string	no
transition	Directs the next workflow state based on the outcome.	Transition	no

Task outcomes can be dynamically configured using workflow expressions to adapt to various conditions and contexts within the workflow.

Example Task Outcome

taskOutcomes:
  - code: Approve
    name: Approve Order
    outcomeDecision: APPROVED
    transition: "ProcessOrderState"
    actions:
      - functionRef:
          refName: LogApproval
          arguments:
            orderId: '${ .task.data.orderId }'

Concept of Task Outcome

Task outcomes are integral to controlling the flow of the workflow based on user decisions. Each outcome is associated with a unique code and name, representing different paths the workflow can take upon task completion. Outcomes can trigger transitions to other states, execute specific actions, and influence the overall workflow execution. In the xFlow task handling UI, outcomes appear as buttons, enabling users to select an appropriate outcome and provide any required data inputs.

Task Actions

Task actions are similar to task outcomes but are designed to execute specific functions or actions without finishing the state. They allow users to perform intermediate actions within the task handling UI. Like task outcomes, task actions are displayed as buttons in the xFlow task handling UI, enabling users to take specific actions that control workflow execution without ending the current state.

Properties of Task Action

Parameter	Description	Type	Required
code	Unique identifier for the action.	string	yes
name	Descriptive name of the action.	string	yes
actions	Defines the actions to be taken when this task action is performed.	array of Action	yes

Example Task Action

taskActions:
  - code: SaveDraft
    name: Save Draft
    actions:
      - functionRef:
          refName: SaveDraftFunction
          arguments:
            taskId: '${ .task.id }'

Concept of Task Action

Task actions enable users to perform specific functions or actions within the task handling UI without completing the state. They are displayed as buttons, allowing users to interact with the workflow by performing intermediate actions. When an action is taken, the action_taken event is fired, which can be handled using task listeners to trigger further actions or processes. Unlike task outcomes, task actions do not conclude the current state but allow for additional workflow control and user interactions.

User Task Form Support

Incorporating a User Task Form UI into a workflow allows for interaction with human operators by presenting forms for data entry. Here, we outline two approaches for defining the User Task Form UI, catering to different levels of customization and development expertise:

Using Lowcoder Tool to Define User Form UI

The Lowcoder tool provides a user-friendly interface for defining forms without needing extensive programming knowledge. It allows developers and business users to quickly create and customize forms that can be integrated into workflows. Forms designed using Lowcoder can capture various data inputs required for task completion, ensuring that all necessary information is collected efficiently.

Defining Advanced Form Using Angular or React with xFlow UI SDK

For developers seeking more advanced customization, forms can be defined using Angular or React in conjunction with the xFlow UI SDK. This approach offers greater flexibility and control over the form's appearance and behavior, allowing for complex interactions and integrations. Developers can leverage the full capabilities of these frameworks to create dynamic, responsive, and feature-rich forms that meet specific business requirements.

Example Workflow with Task Actions

states:
  - name: Init
    type: operation
    actions:
      - functionRef:
          refName: CloneRequestData
          arguments:
            name: request03
            request: '${ .request }'
        actionDataFilter:
          results: '${ .jqResult }'
          toStateData: '${ . }'
    transition: Approval
  - name: Approval
    taskKey: approvalTaskKey
    type: usertask
    formKey: 'LCD#661f784162f95774145bdf9f'
    assignee: '${ .request.approver }'
    taskOutcomes:
      - code: Approve
        name: Đồng ý
        outcomeDecision: APPROVED
        transition: End
      - code: Reject
        name: Từ chối
        outcomeDecision: REJECTED
        transition: End
    taskActions:
      - code: SaveRequest
        name: Lưu
      - code: RequestAdjustment
        name: Yêu cầu điều chỉnh
    taskListeners:
      - taskEvent: created
        actionMode: sequential
        actions:
          - functionRef:
              refName: NotifyWhenUserTaskCreated
              arguments:
                taskName: '${ $state.name }'
                requestCode: '${ .request.code }'
                custName: '${ .request.inputhoten }'
            actionDataFilter:
              useResults: false
      - taskEvent: completed
        actionMode: sequential
        actions:
          - functionRef:
              refName: MergeLoanRequestData
              arguments:
                approver: '${ .request.approver }'
                outcome: '${ $userTask.outcome }'
                editing: '${ $userTask.data.editedRequest.editing }'
                comment: '${ $userTask.data.comment }'
            actionDataFilter:
              results: '${ .jqResult }'
              toStateData: '${ .approverResult }'
      - taskEvent: action_taken
        actionMode: sequential
        actions:
          - subFlowRef:
              workflowId: XBANK_LOAN_ADJUSTMENT
              invoke: async
              onParentComplete: terminate
            condition: '${ $userAction.actionCode == "RequestAdjustment" and ($userAction.data.editedRequest.editing | index( "S1" ) >= 0) }'
            actionDataFilter:
              fromStateData: '${ {"request": .request01 * {"inputhoten": $userTask.data.request01.inputhoten}, "adjRequest": { "editing": "S1" }} }'
              results: '${ $userAction.data.editedRequest }'
              toStateData: '${ .editedRequest01 }'
    transition: End

The ability to set properties dynamically using workflow expressions provides additional flexibility, enabling workflows to adapt to varying contexts and data conditions at runtime. For more detailed information and advanced configurations, refer to the User Task State Documentation.