Task Management

ADMIN DEVELOPER

EZ-Console includes a task subsystem: background work with progress, cancellation, retries, optional artifacts, execution logs, and cron schedules. This page mirrors the framework usages task guide for operators and module authors.

User-facing UI

Area	Path	Permission
Task list	/tasks	task:list
Task detail	/tasks/:id	task:view
Scheduled tasks	/tasks/schedules	task:schedule:list (toggle/trigger need task:schedule:update)
Header dropdown	(layout header)	task:list

• Visibility: Non-admins see only tasks they created; admins see all.
• Polling: Detail page polls while status is pending or running; header dropdown uses GET /api/user-tasks (recent user-category tasks) with faster polling while open.
• Artifacts: Download via GET /api/files/:fileKey when artifact_file_key is set.

System settings

System Settings → Task Settings (requires system:settings:view / system:settings:update):

Setting key	Purpose
task_max_concurrent	Worker concurrency (default 10)
task_log_storage_backend	Where execution logs are stored (default database); options from GET /api/system/task-settings/log-storage-backends

Runners should log with log.GetContextLogger(ctx) so lines are captured into the configured backend.

Permissions (summary)

Code	Typical use
task:list / task:view	List and inspect
task:cancel / task:retry / task:delete	Lifecycle actions
task:schedule:list / task:schedule:update	Cron UI

HTTP APIs (selection)

Method	Path	Notes
GET	/api/tasks	Paginated list; current, page_size, search
GET	/api/tasks/:id	Detail
GET	/api/tasks/:id/logs	Execution logs
POST	/api/tasks/:id/cancel	Cancel
POST	/api/tasks/:id/retry	Retry
DELETE	/api/tasks/:id	Soft delete
GET	/api/user-tasks	Header dropdown (auth only)
GET	/api/task-schedules	Cron definitions
POST	/api/task-schedules/:id/toggle	Enable/disable
POST	/api/task-schedules/:id/trigger	Run once

There is no generic HTTP create for tasks: modules call TaskService.CreateTask from handlers and return the task row to the client.

For developers: create a task

task, err := svc.TaskService.CreateTask(ctx, "export",
    service.WithPayload(`{"scope":"users"}`),
    service.WithMaxRetries(2),
)

Options include WithCategory (user vs system), WithCronScheduleID, etc. Creator comes from the authenticated user on ctx when present.

Example pattern (user export in the main repo): POST /api/authorization/users/export → CreateTask with type user_export → frontend calls addTask from SiteContext so the header dropdown opens. Reuse this pattern for long-running jobs.

Registering task types

Use pkg/taskscheduler:

taskscheduler.RegisterTaskType("export", &ExportRunner{})
// or
taskscheduler.RegisterFuncTaskType("cleanup", func(ctx context.Context, t *model.Task, progressCallback taskscheduler.ProgressCallback, cancelCh <-chan struct{}) (interface{}, error) {
    // ...
    return nil, nil
})

Respect cancelCh; return taskscheduler.ErrCancelled when cancelled. Report progress with progressCallback. Associate artifacts with TaskService.SetTaskArtifact when producing files.

Scheduled (cron) jobs

Register in code with taskscheduler.RegisterScheduledJob (ScheduledJobDef: id, name, cron Spec, task type, payload builder, optional Runner). Definitions are in-memory, not migrated from SQL; changing jobs requires a deploy. When a schedule fires, TaskService.CreateTask runs with category system and the schedule id.

Observability

Counters and gauges such as task_created_total, task_queue_overflow_total, task_queue_length, and task_run_duration_seconds are documented in the framework task guide—useful when tasks stay pending (queue full, missing runner, etc.).

Related topics

• API best practices
• Authentication & authorization
• System settings

---

Need help? Ask in GitHub Discussions.