Workflow


title: "Workflow Processes (PRC)" ---

Workflow Processes (PRC)

The prc submodule of wfl owns the process definitions and the ordered process steps that drive task creation. A WFProcess names a workflow (e.g. "purchase requisition", "sales onboarding") and points at an optional input/output DomainSchema; each WFProcessStep is one step within the process — its handler (page or batch job), assignment defaults, due-day offset, and the initial task status used when the step instantiates a WFTask. The submodule depends on sys.frm for the schema, on wfl.tms for the team a step assigns to, on sys.usr for the user fallback, on com.pop for the optional notification mail group, on wfl.tsk for the task status the step creates tasks in, and on sys.term for the handler class name and parameter value types.

Concepts

Process

A named workflow with an optional input/output schema. The schema describes the data the process consumes and produces.

Process Step

One step within a process. Pins the handler that runs the step (a page or a batch job), the team and optional user the resulting task is assigned to, the due-day offset, the priority, and the initial task status. A step can be flagged createAtProcessStart (skip the trigger and instantiate immediately) or skipInProcessStep (an inert placeholder kept for ordering).

Task Handler Type

Whether the step’s task is handled by a UI page or by a batch job.

Entities

PRC entities

Process (WFProcess)

A named workflow.

FieldDescription

code

Business key (up to 16 characters).

description

Human-readable name.

specSet

Optional input/output DomainSchema for the process.

Process Step (WFProcessStep)

One step within a process.

FieldDescription

wfProcess

Owning process (composite business key with code).

code

Step code (up to 8 characters).

description

Human-readable name.

createAtProcessStart

Whether the step’s task is created immediately at process start. Default false.

skipInProcessStep

Whether the step is skipped during execution. Default false.

daysTillDue

Optional offset (days from creation) applied to the resulting task’s due date.

taskHandlerType

Whether the step is handled by a page or a batch job — see Task Handler Types below. Default PA (Page).

taskHandler

Optional fully-qualified Java class name of the handler.

handlerParameter

Optional parameter passed into the handler.

mailMessageGroup

Optional notification template group used when the step’s task is created.

assignToTeam

Default team the resulting task is assigned to.

assignToUser

Optional default user inside the team.

exceptionTeam

Optional team that picks up the task when it goes into an exception state.

initialTaskStatus

Optional initial status applied to the resulting task.

initialPriority

Initial priority applied to the resulting task. Default M (Medium).

Task Handler Types (WFTaskHandlerType)
CodeNameMeaning

PA

Page

The step is handled by a UI page; a user opens the task and acts on it.

BA

Batch Job

The step is handled by a batch job; the resulting task is processed automatically.

Functionality

Process-step lookup

WFL_PRC_QueryApi exposes two thin lookups: every step of a process (in their stored order) and a single step by (process, code). Other modules use these when resolving the next step to instantiate during process execution and when wiring task creation to a specific step’s handler/assignment defaults.

Public API

WFL_PRC_QueryApi

Read-side facade.

MethodDescription

findAllStepsByWfProcess(WFProcess)

Every step of the process.

findStepByWfProcessAndCode(WFProcess, Code8)

Step by (process, code), or null.

WFL_PRC_CommandApi

This submodule does not provide a command API class. Processes and steps are maintained through the standard CRUD pages.

ViewModel actions

The submodule defines view models for WFProcess and WFProcessStep but does not declare any custom UI actions.


title: "Workflow Teams (TMS)" ---

Workflow Teams (TMS)

The tms submodule of wfl owns the team and team-member configuration that drives task assignment. A WFTeam is a named bucket (optionally tied to a department) that owns workflow tasks; a WFTeamMember is a user’s membership in a team. Other modules call into this submodule when a task is created (the process step’s assignToTeam) and when authorizing whether a given user may pick up or close a task. It depends on com.org for the optional department a team is tied to and on sys.usr for the user.

Concepts

Team

A named group of users responsible for handling a class of tasks. Optionally scoped to a department.

Team Member

A user’s membership in a team. Drives the "is this user allowed to act on this task" check made at task pickup and close.

Entities

TMS entities

Team (WFTeam)

A named group of users.

FieldDescription

code

Business key (up to 8 characters).

description

Human-readable name.

department

Optional department the team belongs to.

Team Member (WFTeamMember)

A user’s membership in a team.

FieldDescription

wfTeam

Owning team (composite business key with user).

user

The member user.

Functionality

Team-membership check

WFTeamReaderService.isUserPartOfTheTeam answers whether a given User is a member of a given WFTeam. It is the seam used by task-pickup and task-close authorization, so the rest of the workflow stack does not have to reason about the link table directly.

Dynamic team-membership matrix

UserViewModel_WFTeamMembers extends the standard user edit page with a dynamic checkbox per existing WFTeam. Loading a user ticks the boxes for the teams they belong to; saving the record removes every existing membership row for the user and re-creates them from the ticked boxes. The pattern is the same as `sys.usr’s group-member matrix.

Public API

WFL_TMS_QueryApi

Read-side facade.

MethodDescription

findTeamByCode(Code8)

Team by code, or null.

isUserPartOfTheTeam(User, WFTeam)

True when the user is a member of the team.

WFL_TMS_CommandApi

This submodule does not provide a command API class. Teams and memberships are maintained through the standard CRUD pages and through the UserViewModel_WFTeamMembers matrix on the user edit page.

ViewModel actions

The submodule defines view models for WFTeam and WFTeamMember but does not declare any custom UI actions. The dynamic team-membership matrix on the user edit page is rendered through UserViewModel_WFTeamMembers.


title: "Workflow Tasks (TSK)" ---

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 DraftProcessed 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.

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.