Tasks configuration automation

Tasks automation contract 2.0.0 exposes configuration through the same authorization and transactional services used by the Tasks UI. The installed developer surface is authoritative for service/version availability. Use user-authorized Action, Command or HttpEndpoint functions for administrative configuration; never move configuration writes into Validation or BeforeSaveMutation.

Tasks configuration is available through HTTP and supported C# automation in the Net Operation Project. Read the installed /openapi/moltaro-config-v1.json for exact HTTP requests and responses: /api/workspace/admin/tasks covers module lifecycle, readiness and security; /api/workspace/tasks/configuration/... covers Definitions, data schemas, Queues, Worker Profiles and signal profiles. Resolve these routes against WORKSPACE_API_BASE_URL, not moltaro.com. Module enablement and configuration permissions are still required by the operations; a documented route grants neither. Older installations may omit Tasks from their public OpenAPI documents and need an update to receive the complete reference. See runtime automation for actual Task commands, background assignment and signals, and Tasks for user workflows. Follow Set up Tasks for the configuration sequence and a first working task.

Supported services

Inject ITasksAutomationStatusQueryService to read the installed module state, capabilities, readiness, and Work Schedule dependency status.

Inject ITaskDefinitionAutomationQueryService to:

• list and read Task Definitions, including their immutable execution mode and Definition-owned interruption reasons;
• read the execution policy and fixed transition matrix, including diagnostics, mode-aware actor availability, and server-owned Outcome grant defaults;
• read due-date and Context policy through GetCreationPolicyAsync;
• discover supported Context families with GetContextFamiliesAsync and search their definition metadata with GetContextCandidatesAsync;
• list completion requirements for an Outcome;
• read server-owned completion DSL authoring metadata; and
• validate an expression without executing it against runtime data.

Inject ITaskDefinitionAutomationCommandService to create, update, activate, deactivate, or delete Task Definitions and to administer owned Outcomes, completion requirements, interruption reasons, execution policies, transition rules, independent Outcome actor grants, and due-date/Context policy.

All three services execute in a separate application scope as the function’s current runtime principal. Status requires module.read; Definition reads require configuration.read; writes and Context family/candidate discovery require configuration.manage. Minimal Context configuration metadata does not require additional Entity or Board administrator permissions and does not grant access to their records. These services do not join a DbContext transaction injected into the function, and there is no Owner or Admin authorization bypass.

Configuration service map

Use the complete current DTO for replacement-style settings and retain fields you are not changing. The returned aggregate supplies the version for the next mutation; a stale request is not repaired by blindly substituting a fresh token.

Configuration	Preferred service pair and responsibility
Definition rules	ITaskDefinitionAutomationQueryService / ITaskDefinitionAutomationCommandService: identity, mode, data definitions, instructions, assignments, permissions, collaboration, outcomes and completion authoring.
Queue operation policy	ITaskQueueAutomationQueryService / ITaskQueueAutomationCommandService: lifecycle, accepted Definitions, Worker sources, dispatchers, prioritization, selection/invocation, return policy and limits.
Global Worker capacity	ITaskWorkerProfileAutomationQueryService / ITaskWorkerProfileAutomationCommandService: Default/specialized profiles, current membership and atomic transfer.
Signal policy	ITaskSignalProfileAutomationQueryService / ITaskSignalProfileAutomationCommandService: profile settings, audiences and Definition/Queue bindings.

Task Input/Working fields and forms use the normal governed Entity/Part configuration surfaces. Completion DSL uses the installed source profile and authoring metadata, not an invented expression AST. Consult Definition setup before changing the admitted types or completion requirements. The Task completion language reference describes the available roots, functions and Outcome-specific restrictions.

Definition mode

Every Task Definition is created with one TaskExecutionModeEnum value:

• Direct assigns future work explicitly to a Responsible without an execution queue.
• Queue assigns future work to an Executor through an execution queue.

The mode is immutable. Update requests carry the persisted value so the server can reject a mode change; use a new Definition when a different mode is needed. Definition configuration does not create Tasks, queue assignments, or execution state.

Queue selection and selector authoring

Queue selection has five modes: Any, First, Last, Auto-assignment and Assignment on request. First is the default. First/Last use the effective prioritization order after eligibility, not another FIFO/LIFO ordering. Configuration does not acquire or assign real Tasks.

ITaskQueueAutomationQueryService.GetSelectionAsync and GetSelectorCandidatesAsync read settings and minimal compatible published-selector metadata. The command counterpart’s UpdateSelectionAsync replaces the complete Selection block with ExpectedQueueRowVersion and OperationId. Preserve the Invocation group when editing the mode, and preserve mode/selector when editing Invocation. Reads require configuration.read; writes require configuration.manage. These permissions do not grant source access or Developer Studio publication.

Auto-assignment and Assignment on request require an enabled, published, compatible Queue selector.

A selector is compatible only with the Tasks SDK version it was built against: after an upgrade that changes the Tasks SDK version (for example 4.2.0 → 5.0.0), customer selectors published on the earlier version are reported as Incompatible and their Queues stop selecting work until the selector is rebuilt and republished (a NetPackage is rebuilt and applied again; a Net Operation Project is rebuilt and activated in full). After the upgrade, check the Queue selector candidates of every Queue that uses Auto-assignment or Assignment on request. The standard algorithm is republished by the upgrade. The module supplies a standard algorithm; an installation can also publish a customer C# algorithm through its Net Operation Project. One selector may be selected by several Queues. Switching to Any/First/Last keeps its identity and invocation settings inactive. Later retirement/disable retains the link and diagnostics, without silently selecting another policy.

In Development choose the Queue selector template. The class declares normal identity metadata and derives from Moltaro.Package.NET.Tasks.Selection.TaskQueueSelector, not Job or Action. There is no Queue attribute or Queue field in the template: select it in Queue settings after publication. The typed SelectAsync receives QueueId, Cause, EvaluationTimeUtc and, for Worker requests, RequestingWorkerId. It returns TaskId/WorkerId proposals or TaskQueueSelectionResult.NoWork. ITaskQueueSelectionCandidates.GetAsync(context) supplies the immutable admitted facts of that invocation. The owning Worker runtime executes selection and rechecks eligibility, capacity, schedule and current configuration before assigning. The selector does not assign or Start tasks itself. Ordinary Run, Action, enqueue and Function Schedule entry points reject direct selector invocation.

Automatic causes default to Task entry, state change and CRON */20 * * * *. ManualEnabled remains a transport member but does not disable authorized dispatcher distribution. Null TimeZoneId follows the workspace zone; an explicit supported time zone is also accepted. The Queue owns durable background evaluation and its CRON cause; this is not a separate user-created Function Schedule. Manual evaluation requires the Queue’s current explicit runtime capability, not merely Configuration Management or Worker membership. Schedule-use policy can use the Worker’s effective Work Schedule for automatic and request-driven assignment. A proposal never bypasses runtime checks.

Queue installation/export uses format 10, including Selection, Invocation, return and schedule-use policy. Older formats and missing required members are rejected. Auto/request import requires an already published compatible selector; it never creates code or functions.

Queue limits and warnings

Use ITaskQueueAutomationQueryService.GetLimitsAsync to read the Queue’s settings and current RowVersion. Use ITaskQueueAutomationCommandService.UpdateLimitsAsync with UpdateTaskQueueLimitsRequest to replace the complete Limits block, including DispatcherExceptions. Preserve the settings you are not changing. Supply ExpectedQueueRowVersion and a stable OperationId; an exact retry returns its historical result without applying the change twice.

Reads require configuration.read, writes require configuration.manage. Dispatcher status and Worker pool membership do not grant configuration access.

• MaxInProgressTasks and MaxPostponedTasks: null means unlimited; zero forbids increasing the corresponding count.
• WipWarningThreshold, PausedWarningThreshold and BlockedWarningThreshold: zero disables the warning; a positive threshold is exceeded only when the count is greater. WIP covers every Task except Done.
• DispatcherExceptions.AllowInProgressOverride and AllowPostponedOverride are explicit, default-off permissions for reason-required exceptions, not a general authorization bypass.

All counts are nonnegative signed 32-bit integers. New queues have unlimited maximums, disabled warnings and disabled exceptions. Settings can be changed in any Queue state. Lowering them does not stop or reassign existing work. Warnings never reject incoming Tasks.

The runtime enforces these settings against persisted Task counts when a command would increase load. Lowering a limit does not rewrite existing assignments or intervals. Signal producers use the current factual conditions; configuration calls do not themselves dispatch tasks.

Worker Profiles and global capacity

ITaskWorkerProfileAutomationQueryService exposes list, detail, capacity, current membership and eligible Worker candidates. Its command counterpart, ITaskWorkerProfileAutomationCommandService, exposes create, metadata update, capacity update, empty-profile deletion, batch assignment/transfer and removal. Both use the current application principal and the common configuration permissions. They do not authorize or assign runtime Tasks.

Exactly one mandatory Default supplies capacity when a Worker has no specialized membership. It cannot be deleted. Create a specialized profile with CreateTaskWorkerProfileRequest, including the current Default’s ExpectedDefaultRowVersion: all capacity settings are copied once. Later Default edits do not change the copy. Specialized profiles have no Active/Inactive state and can be deleted only when empty.

TaskWorkerCapacity contains four nullable nonnegative integer maximums: MaxAssignedTasks, MaxInProgressTasks, MaxPausedTasks, MaxPostponedTasks. Null means unlimited; zero prohibits an increase. BlockedWarningThreshold is zero/off or warns strictly above the positive threshold. The initial Default has InProgress maximum 1, other maximums null, warning zero and four dispatcher exception flags false.

CountAllUnfinishedAssignedTasks initially is true: assigned capacity covers every non-Done Task. False counts only Idle, without a second hidden ceiling. The scope is each Worker across Direct Responsible and Queue Executor work, not the combined load of all members of a profile. Owner and managing Queue Responsible positions do not consume capacity by themselves. Lawful returns to Idle retain an existing assignment even above an Idle-only maximum.

Capacity updates replace the complete block, including DispatcherExceptions, with ExpectedProfileRowVersion and OperationId. Preserve the group not being edited. Lowering settings or changing membership does not stop existing work. Runtime exceptions require the Queue’s dispatcher, the corresponding explicit profile flag and a nonempty reason; they waive neither ordinary Task rights nor Worker/User validity. Readiness, real counts and command-time enforcement remain outside this configuration contract.

Membership commands accept 1–100 distinct Workers atomically. For assignment, send each WorkerId with ExpectedSourceProfileId and ExpectedSourceRowVersion, plus the target’s ExpectedProfileRowVersion. Reordering items is the same command; one stale, hidden or ineligible Worker rejects the whole batch. Removal requires both specialized-profile and Default row versions and returns Workers to Default. There is no intermediate remove/add state. Use fresh source versions from candidate queries and confirm the source-to-target changes before submitting.

New membership requires an active Worker linked to an active User and ordinary Entity View. Candidate filtering is SQL-secured before pagination. A later unavailable member is retained diagnostically and can be explicitly removed; protected Worker fields are not disclosed in its label. Default’s membership list is computed, not a second stored membership table. Snapshots contain profile settings and links, not cached User eligibility or workload.

Exact request/response shapes are in the installation’s SDK reference. Exact retries return historical receipts; no-op commands do not create extra audit events or versions. A missing or invalid Default is a readiness error, never an unlimited fallback. Profile settings remain stored when Tasks is disabled. Profile installation/export is not included; Queue installation uses the separate format 10 contract described above.

Signal Profiles and notification policies

ITaskSignalProfileAutomationQueryService lists/reads profiles and resolves named subjects under current configuration.read. Its command counterpart creates, updates and deletes profiles and binds Definitions/Queues under configuration.manage. Use current versions and stable OperationId for exact retry. Configuration rights do not grant Task access or signal acknowledgement.

TaskSignalProfileSettings contains Enabled, WarningBeforeDueMinutes, DangerBeforeDueMinutes and SignalPolicies. Optional thresholds are whole minutes from 0 to 43200; null disables one. If both are present, Warning must be greater than Danger. A Definition binding takes precedence over Queue, even when disabled; removing the Definition binding permits Queue inheritance. Overdue needs no profile.

A policy selects a supported signal, authorized audience, optional additional subjects and notification transitions: Activation, SeverityIncrease and AudienceChange. A profile supports at most eleven distinct signal policies and 64 distinct additional subjects per policy. Selecting a recipient never bypasses their current access. Shared acknowledgement is supported only for designated administrative exceptions and does not resolve the underlying condition.

Profiles have no ordered steps or automatic Task mutations. The runtime retains ordinary History and shared signal/notification delivery. See runtime signals.

Configuration Management

The Workspace-scoped Tasks role is Configuration Management, key configuration-management. It grants common configuration.read and configuration.manage for Definitions, Queues and Worker Profiles. Manifest 6 replaces the old Queue Management key and per-catalog permission keys without aliases; upgrade preserves stored mappings and existing administrative access. Viewer remains read-only. Platform Owner/Admin retains the separate module lifecycle and security-mapping gate. Creator, Observer, Task administrator and Queue dispatcher remain scoped operational roles, not configuration grants.

Due date and Context

CreationPolicy is included in Definition details. New Definitions start with an optional due date, optional Context and an empty allowed-definition list. An empty list forbids every non-null Context; it is not a wildcard.

TaskDueDateModeEnum defines the creation requirement:

Value	Meaning
NotUsed (0)	A due date must not be supplied.
Optional (1)	A due date may be supplied.
Required (2)	A due date is required when creating the Task.

There is no later checkpoint, expected duration or automatic deadline calculation. Context identifies the business object the work concerns, not an assignment authority or an orchestration setting.

Use UpdateCreationPolicyAsync with UpdateTaskCreationPolicyRequest to change DueDateMode and ContextRequired. Add an allowed definition before making Context required. Removing its last admission while Context is required is rejected; the server does not silently make Context optional.

Use AddContextDefinitionAsync and RemoveContextDefinitionAsync for individual admissions. Each mutation carries the current ExpectedDefinitionRowVersion and a stable OperationId; use the returned Definition and version for the next mutation. The supported canonical identities are:

ModuleKey	ResourceKind	ContextResourceId
core.entity	EntityInstance	An Entity Definition ID.
Boards	BoardItem	A Board configuration ID.

An admission does not contain a concrete object’s ResourceObjectId. Entity candidates include standalone Data and Association definitions, including system definitions, but not Parts or definitions pending deletion. New Board admissions require an enabled Boards module and an active Board. Candidate queries load configuration metadata only, not records, Board Items or counts. Unsupported families and unavailable providers cannot admit new definitions.

Saved admissions block deletion of their target until explicitly removed, even when the Task Definition is inactive. Deactivating a Board or disabling its module retains the admission with an availability diagnostic. Activating a Task Definition revalidates its saved admissions.

These operations configure admissibility; they do not create Task Instances, prove that a concrete object exists or belongs to a Board, or authorize runtime data access. The linked object’s security remains independent.

Execution policy and transition matrix

Every Definition owns the same fixed state catalog: Idle, InProgress, Paused, Blocked, Postponed, and Done. The transition matrix contains one server-owned row for each supported state pair. A row stores only whether the pair is enabled and which mode-specific actor kinds may initiate it. It has no Outcome reference, operation kind, authored code, or sort order.

Outcomes own a separate actor-grant collection. Completion requires the same actor to be granted by both the current state-to-Done row and the selected Outcome, followed by successful Completion Eligibility evaluation. Outcome creation uses server defaults for its mode and meta-type; later meta-type changes do not silently rewrite explicit grants.

UpdateExecutionPolicyAsync configures the Queue managing Responsible, fixed postponement delay and lifetime maximum, and nullable Pause/Blocked warning thresholds. The managing Responsible is not used, optional, or required at creation: QueueResponsibleRequired (a historical name) makes the participant available, and ResponsibleRequiredOnCreate makes it required when a Task is created. If the request omits ResponsibleRequiredOnCreate, newly enabling the participant makes it required and an enabled participant keeps its setting; disabling the participant clears it. Requiredness applies only to creation. Disabling Queue Responsible after it has grants requires the explicit removal flag and is rejected if it would strand an enabled transition or Outcome. A managing Responsible kept on existing Tasks after that grants no access and can only be cleared by a Task administrator. UpdateTransitionRuleAsync and UpdateOutcomeActorGrantsAsync require the current Definition and child RowVersions plus a stable OperationId.

These APIs configure current runtime rules. They do not move a Task, select an Outcome, run a timer, or create queue work.

Interruption reasons

Each Definition owns an initially empty list of reasons classified as Pause, Blocked, or Postponed. Codes are normalized and unique across the entire Definition. Unused reasons may be renamed, reclassified, disabled, reordered, or deleted. A referenced reason cannot be deleted; the governed database foreign key rejects that mutation atomically.

Create, update, and delete requests carry the current Definition RowVersion, and updates/deletes also carry the reason RowVersion. Each command requires a stable OperationId. Preserve it only for an exact retry after an unknown outcome: an exact replay returns the stored result without repeating audit, cache invalidation, or storage work, while a changed payload conflicts.

Successful commands preserve application validation, optimistic concurrency, Definition advisory locking, owned-storage transactions, audit, command receipts, and Tasks cache invalidation. Read the returned aggregate before issuing the next mutation so subsequent requests use current RowVersions.

Reference

Use the installation’s developer-surface catalog as the authoritative injectable-service allow-list. Exact interface, request, result, and enum members are in the Tasks XML reference.

For operational creation, assignment, transitions and completion, use the Tasks instance SDK. It exposes both the primary service layer and public writable generated EF entities. Configuration permissions do not grant task-operation permissions.