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
ProcessA named workflow with an optional input/output schema. The schema describes the data the process consumes and produces.
Process StepOne 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) orskipInProcessStep(an inert placeholder kept for ordering).Task Handler TypeWhether the step’s task is handled by a UI page or by a batch job.
Entities
Process (WFProcess)
A named workflow.
| Field | Description |
|---|---|
| Business key (up to 16 characters). |
| Human-readable name. |
| Optional input/output |
Process Step (WFProcessStep)
One step within a process.
| Field | Description |
|---|---|
| Owning process (composite business key with |
| Step code (up to 8 characters). |
| Human-readable name. |
| Whether the step’s task is created immediately at process start. Default |
| Whether the step is skipped during execution. Default |
| Optional offset (days from creation) applied to the resulting task’s due date. |
| Whether the step is handled by a page or a batch job — see Task Handler Types below. Default |
| Optional fully-qualified Java class name of the handler. |
| Optional parameter passed into the handler. |
| Optional notification template group used when the step’s task is created. |
| Default team the resulting task is assigned to. |
| Optional default user inside the team. |
| Optional team that picks up the task when it goes into an exception state. |
| Optional initial status applied to the resulting task. |
| Initial priority applied to the resulting task. Default |
Task Handler Types (WFTaskHandlerType)
| Code | Name | Meaning |
|---|---|---|
| Page | The step is handled by a UI page; a user opens the task and acts on it. |
| 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.
| Method | Description |
|---|---|
| Every step of the process. |
| Step by (process, code), or |
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
TeamA named group of users responsible for handling a class of tasks. Optionally scoped to a department.
Team MemberA 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
Team (WFTeam)
A named group of users.
| Field | Description |
|---|---|
| Business key (up to 8 characters). |
| Human-readable name. |
| Optional department the team belongs to. |
Team Member (WFTeamMember)
A user’s membership in a team.
| Field | Description |
|---|---|
| Owning team (composite business key with |
| 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.
| Method | Description |
|---|---|
| Team by code, or |
| 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 ListA process instance — one tree of tasks created from a
WFProcessfor a specific department, with an optional source document line and reference to a domain entity.TaskA 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 StatusWhere the task is in its lifecycle — Pending, Assigned, In Progress, Waiting, Exception, Canceled, Completed, or Locked.
Task FlowWhether the task is handled manually by a user (
M) or automatically by a batch job (A).Status Event/Transfer Event/Plan EventThree immutable timestamped event streams on a task: status changes, team/user re-assignments, and priority/due-date changes. Each event has a
Draft→Processedlifecycle.Task MailA linking row that attaches a
MailMessagefromcom.popto a task — the audit trail of mail traffic about a task.Task Assignment ModeA 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
Task List (WFTaskList)
A process instance.
| Field | Description |
|---|---|
| Business key (a |
| The process the list runs (final). |
| Owning department (final). |
| Optional originating document line. |
| Optional domain-entity class name the list is about. |
| Optional domain-entity id. |
| Optional domain-entity business code. |
Task (WFTask)
One unit of work within a task list.
| Field | Description |
|---|---|
| Owning list (composite business key with |
| Position of the task within the list (final). |
| Owning department (final). |
| The process step this task realises (final). |
| When the task was created (final). |
| Optional free-form description (final). |
| Optional external reference (final). |
| Optional partner the task is about (final). Validated to belong to the same partner. |
| Team the task was initially assigned to (final). |
| Optional initial user (final). |
| Initial status (final). |
| Initial priority (final). |
| Initial due date/time (final). |
| Optional in-progress message a handler can write to. |
| Optional exception text when the task is in |
| Optional domain-entity reference (operational, internal). |
| Current team — derived from the latest processed transfer event. |
| Optional current user — derived from the latest processed transfer event. |
| Optional completion timestamp — set by the latest status event that puts the task into |
| Current priority — derived from the latest processed plan event. |
| Current due date/time — derived from the latest processed plan event. |
| Current status — derived from the latest processed status event. |
| Whether the task is locked (e.g. someone is editing). Default |
A validation rule enforces that the task’s department differs from the task list’s department (cross-department workflow).
Task Statuses (WFTaskStatus)
| Code | Name | Meaning |
|---|---|---|
| Pending | Created but not yet assigned to a user. |
| Assigned | Claimed by a user; not started. |
| In Progress | The user is actively working on the task. |
| Waiting | Paused waiting for input or a downstream event. |
| Exception | The task ran into an error and is awaiting attention. |
| Canceled | The task was cancelled. |
| Completed | The task was finished. |
| Locked | The task is temporarily locked. |
Task Flows (WFTaskFlow)
| Code | Name | Meaning |
|---|---|---|
| Manual | Handled by a user through a UI page. |
| Automatic | Handled by a batch job. |
Task Assignment Modes (WFTaskAssignment)
| Value | Meaning |
|---|---|
| Use the user passed in by the caller (or none) when adding the task. |
| Use the user configured on the process step ( |
Status Event (WFTaskStatusEvent)
An immutable record of a status change.
| Field | Description |
|---|---|
| Owning task (composite business key with |
| When the change happened (final). |
| The user who made the change (final). |
| The new status (final). |
| Lifecycle flag. |
Transfer Event (WFTaskTransferEvent)
An immutable record of a re-assignment.
| Field | Description |
|---|---|
| Owning task (composite business key with |
| When the transfer happened (final). |
| The user who made the change (final). |
| New team (final). |
| Optional new user (final). |
| Lifecycle flag. |
Plan Event (WFTaskPlanEvent)
An immutable record of a priority or due-date change.
| Field | Description |
|---|---|
| Owning task (composite business key with |
| When the change happened (final). |
| The user who made the change (final). |
| New priority (final). Default |
| New due date/time (final). |
| Lifecycle flag. |
Task Mail (WFTaskMail)
A link from a task to a mail message.
| Field | Description |
|---|---|
| Owning task (composite business key with |
| 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
WFTaskStatusEventif the task’s current status differs fromnewStatus. Validates that the task is assigned to a user before moving to any "active" status. Returns the new event, ornullif no change was needed.transferTaskIfRequired(task, team, user?)Records a fresh
WFTaskTransferEventif the task’s current assignment differs from the supplied team/user. Returns the new event, ornullif 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.
| Method | Description |
|---|---|
| The single task in a list for a given step code; raises if zero or more than one match. |
| Every task of a list. |
| Task by primary id. |
| 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.
| Method | Description |
|---|---|
| Creates a fresh task list and instantiates the steps flagged |
| Adds a single task to an existing list under a specific process step. |
| Records a status event when the new status differs from the current. |
| Records a transfer event when the new assignment differs from the current. |
| Updates the task’s free-form progress message. |
| Sets the task’s exception message. |
| Clears the exception message. |
| Stores the task’s reference to a domain entity. |
| Convenience pass-through to the step lookup in |
| Disabled — always raises a business exception (workflow history must be preserved). |
Cross-module extension interfaces
HasWorkflowImplemented by domain entities (and their view models) that own a
WFTaskList. ExposesgetTaskList().IsTaskReadThe 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).IsTaskWriteThe write-side seam (
setExecutedByUser,setTaskCompleted,setTaskCanceled).
ViewModel actions
| Action | User-visible effect |
|---|---|
| Assigns the current user to the task and moves it to Assigned. |
| Releases the task back to its team. |
| Transfers the task to the team chosen on the form. |
| Navigates to the page configured on the task’s process step. |
| Renders the task’s full event history. |
| Processes a drafted event and replays it onto the task’s |
| Records an arbitrary new status — for development/recovery. |