Tasks & schedules

A task (TaskMaster) is a unit of work made up of task actions (TaskAction sub-items). A task schedule (TaskSchedule) is a grouping container that tasks can join. Both carry a string Status with a small state machine — and both can move themselves forward automatically as their children progress.

Task states

TaskMaster.Status: "ToDo", "InProgress", "Completed", "Cancelled". Every task is created as ToDo, with each of its actions also ToDo.

From \ trigger	StartTask	EndTask	CancelTask	UpdateTaskStatus	Action change (UpdateTaskActionStatus)
ToDo	→ InProgress (StartTime)	→ Completed (EndTime + CompletedBy)	→ Cancelled	set status / start / complete	action leaves ToDo ⇒ auto-start → InProgress
InProgress	400 already-started	→ Completed	→ Cancelled	complete / re-cascade	all actions done ⇒ auto-complete → Completed
Completed	400	200 idempotent	400	rejected silently (action-only edits still apply)	action edits allowed; task unchanged
Cancelled	400	400	400	rejected	—

Action states and the auto cascades

Each TaskAction has its own TaskActionState: ToDo, InProgress, Completed (terminal for the action), or NoActionRequired (counts as "done"). Two task-level flags — both defaulting to true — cascade action progress up onto the task:

• AutoStart: the first time any action moves out of ToDo/NoActionRequired, a ToDo task flips to InProgress and stamps StartTime.
• AutoComplete: when an InProgress task's actions are all Completed/NoActionRequired, the task flips to Completed and stamps EndTime + CompletedByUserId.

Manual complete bypasses the actions: EndTask (or UpdateTaskStatus = Completed) completes the task regardless of action states.

Terminal states aren't fully frozen

Once a task is Completed, task-state edits are silently ignored — but action statuses can still be set. This is deliberate: the internal auto-complete listener (below) may fire after the task is already complete. Deleting a task is not lifecycle-gated either — a Completed task deletes with 200.

Cross-domain auto-complete

Task actions can be system-typed links to other domain records. Completing a linked Order, Inventory, CycleCount, ItemSearch, or ServiceRecord auto-completes the corresponding system-type TaskAction — which then cascades AutoStart/AutoComplete onto the task, exactly as if a user had ticked the action. (Internally: TaskResolutionEventHandler → TaskStateListener.UpdateStateAsync.) This is the state-machine counterpart to the TaskId/TaskName fields you see on order summaries. See Service records and the Order lifecycle for the emitting side.

Task schedule states

TaskSchedule.Status: "Pending", "InProgress", "Complete", "Cancelled" — note Complete, not Completed (it differs from the task enum; match strings accordingly).

From \ trigger	StartTaskSchedule	EndTaskSchedule	CancelTaskSchedule	UpdateTaskSchedule (auto-cascade)
Pending	→ InProgress (StartTime)	400 not-InProgress	→ Cancelled	any child task ≠ ToDo/Cancelled ⇒ auto-start → InProgress
InProgress	400 already-started	→ Complete (EndTime)	→ Cancelled	all child tasks Completed/Cancelled ⇒ auto-complete → Complete
Complete	400	400	400	no state change
Cancelled	400	400	400	no state change

A schedule is a grouping container, not a recurrence engine

A TaskSchedule does not spawn tasks. There is no code that generates tasks from a schedule — RunDate is descriptive metadata only. Tasks join a schedule at task-create time via AddTaskDto.TaskScheduleId. If you need recurring tasks, your client creates them.

Two behaviours worth calling out:

• The schedule's auto cascade only re-evaluates during updatetaskschedule. Starting or completing a child task does not push the schedule forward on its own — the schedule catches up the next time it is updated, or when you explicitly Start/End it.
• EndTaskSchedule is a manual complete: it works from InProgress regardless of child task states (the auto path is the one that requires all children Completed/Cancelled).

"Open" schedules — as counted by GetMyOpenTasksCount on the schedule controller — are those not in Complete/Cancelled.

Audit and events

Neither entity has a transaction-history table — the audit trail is the event stream plus the standard audit columns (EntityVersionNo, modified-by/-on). Events: TaskCreated, TaskStateChanged, TaskCompleted, TaskUpdated, TaskDeleted; TaskScheduleCreated, TaskScheduleStateChanged, TaskScheduleUpdated, TaskScheduleCompleted, TaskScheduleDeleted.

Related

• Service records — the ServiceRecordCompleted event is one of the cross-domain auto-complete triggers.
• Order lifecycle — order completion likewise auto-completes a linked task action.
• Errors & response conventions — the 400 validation-array shape used by all the rejected transitions above.