Background Tasks
1. What it is
Background Tasks is the platform-wide tracker for long-running operations. When anyone triggers a large import, export, or bulk update, the work runs in the background and a task card tracks its progress, outcome, and errors. The page is at Background Tasks in the user dropdown menu (top-right navigation bar).
- Enablement: Background Tasks is a built-in platform feature — not a licensed app. It is available to every authenticated user automatically. There is no admin toggle to enable or disable it.
- What it is not: Background Tasks is not an admin dashboard across all users. Every user sees only their own tasks. There is no cross-user view.
2. Standing it up
Nothing to configure. Background Tasks is live for every user from the moment they have an account.
- Any user triggers a long-running operation from elsewhere in the platform — for example, importing users from a CSV, exporting a Power Table, or running a bulk leave-balance recalculation.
- A task card appears at User menu → Background Tasks with a live progress bar.
- A badge on the Background Tasks menu item shows the count of active (pending or processing) tasks.
- When the task finishes, the platform sends an email notification with a summary and a link back to the task detail page.
There are no prerequisites, no role assignments, and no settings to configure before Background Tasks works.
3. How it fits together
Task lifecycle
Every background task moves through a fixed set of statuses:
- Pending — the task is queued and waiting for a worker to pick it up.
- Processing — the worker is actively running the operation. A progress bar shows records processed out of total.
- Completed — the operation finished. If some individual records failed (e.g. invalid rows in an import), the task still completes but shows an error count alongside the success count.
- Failed — the entire operation could not finish (e.g. the source file was unreadable or an unrecoverable error occurred).
- Cancelled — an admin or the user stopped the task from the UI, or the platform cancelled it automatically (see below).
A cancelled status always wins: if a user cancels a task while it is processing, the task transitions to cancelled regardless of any in-flight work.
What creates tasks
Background tasks are created automatically by more than 50 operations across the platform. The most common categories:
- Imports — user CSV imports, leave-balance imports, skill imports, policy imports, ticket imports, Power Table imports.
- Exports — user exports, leave-balance exports, Power Table exports, conversation exports.
- Bulk operations — bulk approve timesheets or schedules, bulk user actions (deactivate, restore, permanently delete), bulk skill verification, bulk leave-policy assignment.
- Sample data — loading or clearing sample data from Admin settings.
- AI drafts — content generation tasks triggered by AI features.
Each task type is labelled automatically (e.g. “Import: Users”, “Export: Leave Balance”, “Sample data: Shifts”).
Email notifications
When a task completes or fails, the platform sends an email to the user who started it. The completion email includes a summary with total, successful, and failed record counts, plus up to 10 inline errors. The failure email includes the error details. These emails always send — they are not in a user-configurable notification category.
One exception: scheduled CI pipeline tasks do not send these emails by default, unless that particular task type is explicitly opted in.
Automatic cancellation
When an admin disables a marketplace app, all active background tasks associated with that app are cancelled automatically. Additionally, when a job starts executing, it checks whether the associated app is still enabled — if it was disabled between enqueue and execution, the task is cancelled before any work begins.
4. Running it
Viewing your tasks
- Click your user avatar (top-right) and select Background Tasks.
- The page shows all your tasks, newest first, 25 per page.
- Use the status tabs (All Tasks, Pending, Processing, Completed, Failed, Cancelled) to filter by status.
- Use the Task type dropdown to filter by operation type (e.g. show only imports).
- Active tasks display a live progress bar that updates automatically. If progress stalls for more than two minutes, a notice appears: “This is taking longer than expected.”
Cancelling an active task
From the task card, click Cancel. A confirmation dialog explains that the work stops but the task row is kept in your history. The task transitions to the cancelled status and the underlying job is discarded so it cannot retry.
Downloading an export file
When an export task completes, a Download button appears on the task card. Click it to download the generated file (CSV, Excel, etc.). The download is only available after the task reaches the completed status.
Viewing task details
Click the task title to open the detail page. This shows the full task card, a description (if the originating operation provided one), and a Result Data section with any structured output the job recorded. The detail page also shows all retained errors (the list view caps at 25).
Dismissing a finished task
Click Dismiss on any finished (completed, failed, or cancelled) task to remove it from your history. This deletes the task record permanently.
Clearing history
Click Clear History at the top of the page to remove all finished tasks matching your current filter. Active tasks are never cleared — the button only affects completed, failed, and cancelled tasks.
5. Settings
Background Tasks has no dedicated settings surface. It is a built-in platform feature with no configurable options. The behaviour is fixed:
| Behaviour | Value | Source |
|---|---|---|
| Default task status | Pending | Every task starts here the moment it is queued |
| Progress poll interval | 3 seconds | How often an active task card refreshes itself |
| Stall warning threshold | 2 minutes of no progress change | When the “taking longer than expected” notice appears |
| Tasks per page | 25 | The Background Tasks list |
| Completion/failure email | Always sent (not user-configurable) | Goes to whoever started the task |
6. More help
- AI Operations — the admin surface for governing autonomous AI agents (pause, resume, approvals, trust levels)
- Ask AI — the assistant answers questions about Background Tasks from these articles.