Workflow Tasks (TSK)

The tsk submodule of wfl is the heart of the workflow engine. It owns the task list (one per process instance), the tasks within it, and the three event streams — status, transfer, plan — that drive every state change. A task’s current assignment, status, priority, and due date are all derived from replaying the events on top of its initial state. The submodule also defines the cross-module extension interfaces (HasWorkflow, IsTaskRead, IsTaskWrite) that domain entities elsewhere implement to plug into the workflow framework. It depends on wfl.prc for the process and step definitions, on wfl.tms for teams, on sys.usr for users, on com.par for partners and contacts, on com.org for the department, on com.pop for mail attachments, and on acc.doc for the optional source document line.

Concepts

Task List

A process instance — one tree of tasks created from a WFProcess for a specific department, with an optional source document line and reference to a domain entity.

Task

A single unit of work inside a task list. Created from a WFProcessStep; carries the initial team assignment, user, status, priority, and due date as final fields, and the current values as derived business-information fields fed by the event streams.

Task Status

Where the task is in its lifecycle — Pending, Assigned, In Progress, Waiting, Exception, Canceled, Completed, or Locked.

Task Flow

Whether the task is handled manually by a user (M) or automatically by a batch job (A).

Status Event / Transfer Event / Plan Event

Three immutable timestamped event streams on a task: status changes, team/user re-assignments, and priority/due-date changes. Each event has a Draft → Processed lifecycle.

Task Mail

A linking row that attaches a MailMessage from com.pop to a task — the audit trail of mail traffic about a task.

Task Assignment Mode

A small enum (DEFAULT / PROCESS_STEP_USER) that says whether a newly added task takes the assigned user from the caller or from the process step’s configured user.

Entities

TSK entities

Task List (WFTaskList)

A process instance.

FieldDescription

code

Business key (a WFTaskListCode, final).

process

The process the list runs (final).

department

Owning department (final).

sourceDocumentLine

Optional originating document line.

domainObjectType

Optional domain-entity class name the list is about.

domainObjectKey

Optional domain-entity id.

domainObjectCode

Optional domain-entity business code.

Task (WFTask)

One unit of work within a task list.

FieldDescription

taskList

Owning list (composite business key with lineNumber, final).

lineNumber

Position of the task within the list (final).

department

Owning department (final).

processStep

The process step this task realises (final).

startDateTime

When the task was created (final).

description

Optional free-form description (final).

referenceCode

Optional external reference (final).

partner / partnerContact

Optional partner the task is about (final). Validated to belong to the same partner.

initialAssignedToTeam

Team the task was initially assigned to (final).

initialAssignedToUser

Optional initial user (final).

initialTaskStatus

Initial status (final).

initialPriority

Initial priority (final).

initialDueDateTime

Initial due date/time (final).

progressMessage

Optional in-progress message a handler can write to.

exceptionMessage

Optional exception text when the task is in Exception state.

domainObjectKey / domainObjectCode

Optional domain-entity reference (operational, internal).

biAssignedToTeam

Current team — derived from the latest processed transfer event.

biAssignedToUser

Optional current user — derived from the latest processed transfer event.

biCompletionDateTime

Optional completion timestamp — set by the latest status event that puts the task into Completed.

biPriority

Current priority — derived from the latest processed plan event.

biDueDateTime

Current due date/time — derived from the latest processed plan event.

biTaskStatus

Current status — derived from the latest processed status event.

biLocked

Whether the task is locked (e.g. someone is editing). Default false.

A validation rule enforces that the task’s department differs from the task list’s department (cross-department workflow).

Task Statuses (WFTaskStatus)

CodeNameMeaning

PE

Pending

Created but not yet assigned to a user.

AS

Assigned

Claimed by a user; not started.

IN

In Progress

The user is actively working on the task.

WA

Waiting

Paused waiting for input or a downstream event.

EX

Exception

The task ran into an error and is awaiting attention.

CA

Canceled

The task was cancelled.

CO

Completed

The task was finished.

LO

Locked

The task is temporarily locked.

Task Flows (WFTaskFlow)

CodeNameMeaning

M

Manual

Handled by a user through a UI page.

A

Automatic

Handled by a batch job.

Task Assignment Modes (WFTaskAssignment)

ValueMeaning

DEFAULT

Use the user passed in by the caller (or none) when adding the task.

PROCESS_STEP_USER

Use the user configured on the process step (assignToUser).

Status Event (WFTaskStatusEvent)

An immutable record of a status change.

FieldDescription

wfTask

Owning task (composite business key with eventDateTime).

eventDateTime

When the change happened (final).

user

The user who made the change (final).

biTaskStatus

The new status (final).

processed

Lifecycle flag.

Transfer Event (WFTaskTransferEvent)

An immutable record of a re-assignment.

FieldDescription

wfTask

Owning task (composite business key with eventDateTime).

eventDateTime

When the transfer happened (final).

user

The user who made the change (final).

assignedToTeam

New team (final).

assignedToUser

Optional new user (final).

processed

Lifecycle flag.

Plan Event (WFTaskPlanEvent)

An immutable record of a priority or due-date change.

FieldDescription

wfTask

Owning task (composite business key with eventDateTime).

eventDateTime

When the change happened (final).

user

The user who made the change (final).

priority

New priority (final). Default M.

dueDateTime

New due date/time (final).

processed

Lifecycle flag.

Task Mail (WFTaskMail)

A link from a task to a mail message.

FieldDescription

wfTask

Owning task (composite business key with mailMessage).

mailMessage

The mail message attached to the task.

Functionality

Task-list creation

WFTaskWriterService.createTaskList creates a fresh WFTaskList for a process and department, then walks the process’s steps and instantiates a WFTask for every step flagged createAtProcessStart. Used by callers that own the upstream domain entity and want to spin up the workflow for it.

Task addition

addTask adds a single task to an existing list against a specific process step. It resolves the team and user from either the caller’s input or the process step’s defaults (driven by the WFTaskAssignment mode), captures the initial status/priority, and persists the task in Pending.

Status / transfer changes

WFTaskEventWriterService is the seam every status or transfer change goes through:

changeTaskStatusIfRequired(task, newStatus)

Records a fresh WFTaskStatusEvent if the task’s current status differs from newStatus. Validates that the task is assigned to a user before moving to any "active" status. Returns the new event, or null if no change was needed.

transferTaskIfRequired(task, team, user?)

Records a fresh WFTaskTransferEvent if the task’s current assignment differs from the supplied team/user. Returns the new event, or null if no change was needed.

Both methods handle event creation only; processing the event (replaying it onto the task’s bi* fields) happens through the matching action writer.

Event replay

WFTaskEventReplayService is the engine that derives the task’s current state. It reads every processed event for a task in chronological order and applies it to the task’s bi* fields — biTaskStatus, biAssignedToTeam/biAssignedToUser, biPriority/biDueDateTime, biCompletionDateTime. Triggered when an event is confirmed (its processed flag flipped to true) by the matching action writer (WFTaskStatusEventActionWriter, WFTaskTransferEventActionWriter, WFTaskPlanEventActionWriter).

Event rendering

WFTaskEventRenderService produces a human-readable HTML rendering of a task’s full event history — the source for the Events UI button.

Task progress and exception

setTaskProgress(task, message) updates the task’s progressMessage (a free-form note the handler keeps current). setTaskError(task, exceptionMessage) writes the supplied text into exceptionMessage; clearWorkflowTaskError(task) empties it. Used by automatic handlers to surface their state in the UI.

Reference-entity link

setTaskReferenceEntity(task, entity) populates the task’s internal domainObjectKey/domainObjectCode from a DomainEntity so the UI can navigate from the task to the underlying domain row.

UI actions

The user-facing WFTaskViewModel exposes the task buttons that drive the manual flow. The Claim action assigns the current user to the task and moves it from Pending to Assigned; Unclaim releases the task back to the team. Transfer records a transfer event to the chosen transferToTeam. Open Page navigates to the page configured on the process step. Events renders the event history. The "My Tasks" filter on the form restricts the grid to tasks the current user is assigned to.

A separate developer view model (WFTaskDevViewModel) exposes a Change Status action that records an arbitrary new status — used to recover stuck tasks during development.

Public API

WFL_TSK_QueryApi

Read-side facade.

MethodDescription

findOneTaskByTaskListAndProcessStepCode(…​)

The single task in a list for a given step code; raises if zero or more than one match.

findAllTasksByTaskList(WFTaskList)

Every task of a list.

getById(UUID)

Task by primary id.

findAllPendingTasksOrderByTeamAndDueDate()

Every pending task across the system, ordered by team and due date — feeds the workflow inbox view.

WFL_TSK_CommandApi

Write-side facade. All methods delegate to WFTaskWriterService or WFTaskEventWriterService.

MethodDescription

createTaskList(…​)

Creates a fresh task list and instantiates the steps flagged createAtProcessStart.

addTask(…​)

Adds a single task to an existing list under a specific process step.

changeTaskStatusIfRequired(HasTrace, WFTask, WFTaskStatus)

Records a status event when the new status differs from the current.

transferTaskIfRequired(HasTrace, WFTask, WFTeam, User?)

Records a transfer event when the new assignment differs from the current.

setTaskProgress(WFTask, Description30)

Updates the task’s free-form progress message.

setTaskError(WFTask, ExceptionMessage)

Sets the task’s exception message.

clearWorkflowTaskError(WFTask)

Clears the exception message.

setTaskReferenceEntity(WFTask, DomainEntity)

Stores the task’s reference to a domain entity.

getProcessStepByCode(HasTrace, WFProcess, Code8)

Convenience pass-through to the step lookup in wfl.prc.

removeTask(HasTrace, WFTask)

Disabled — always raises a business exception (workflow history must be preserved).

Cross-module extension interfaces

HasWorkflow

Implemented by domain entities (and their view models) that own a WFTaskList. Exposes getTaskList().

IsTaskRead

The read-side seam for entities that wrap a WFTask. Exposes the executed-by user, the start/completion timestamps, the task flow, and helpers (assertTaskIsNotCompleted, assertTaskUserIsValid, validateAfterTaskCompleted).

IsTaskWrite

The write-side seam (setExecutedByUser, setTaskCompleted, setTaskCanceled).

ViewModel actions

ActionUser-visible effect

executeClaimTask (on Task)

Assigns the current user to the task and moves it to Assigned.

executeUnclaimTask (on Task)

Releases the task back to its team.

executeTransferTask (on Task)

Transfers the task to the team chosen on the form.

executeOpenTaskPage (on Task)

Navigates to the page configured on the task’s process step.

executeDisplayTaskEvents (on Task)

Renders the task’s full event history.

confirm (on Status / Transfer / Plan Event)

Processes a drafted event and replays it onto the task’s bi* fields.

changeStatus (on Task Dev VM)

Records an arbitrary new status — for development/recovery.