# Background Tasks Demo — "Apply Discount" bulk action
A minimal, video-ready demo showing the Webiny bulk-actions → background-tasks story.
One artifact spans all three posts.
## What's here
Organized by side (`api/` + `admin/`), with a full-stack entry component:
| File | Role |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `ApplyDiscountExtension.tsx` | **Entry.** Full-stack component — wires up the API and Admin extensions below. |
| `api/ApplyDiscountBulkAction.ts` | **API.** A custom `EntriesBulkAction`. Webiny auto-generates a background task from it. Emits a websocket message per processed entry. |
| `admin/Extension.tsx` | **Admin entry.** Registers the bulk-action button + the websocket listener. |
| `admin/ApplyDiscountAction.tsx` | **Admin.** The bulk-action button that triggers the task. |
| `admin/DiscountAppliedEventHandler.ts` | **Admin.** Websocket listener that toasts when a discount is applied. |
| `../models/ProductModel.ts` | The demo CMS model (`product`, with `price` + `onSale`). |
| `../models/ProductCategoryModel.ts` | Referenced by Product; registered so the category picker isn't dangling. |
Registered in `webiny.config.tsx` as `` (plus the two model
`` entries under `extensions/models/`).
## The key idea
A custom bulk action is **just two methods** — `loadData` and `processData`. You never
write scheduling, batching, retry, or timeout-resume code. For every registered
`EntriesBulkAction`, Webiny automatically generates:
- a **list** background task — `hcmsBulkListApplyDiscountEntries`
- a **process** background task — `hcmsBulkProcessApplyDiscountEntries`
- a GraphQL mutation — `bulkActionProduct(action: ApplyDiscount, ...)`
The action name `applyDiscount` is PascalCased into those ids/enum values, which is why
the frontend triggers it with `action: "ApplyDiscount"`.
### Convergence (important)
The tasks engine calls `loadData` **repeatedly** until it returns zero entries — after
each processing round it re-lists to check for more work. So `loadData` must exclude
entries it has already processed, or the task never finishes (it re-processes the same
entries until it hits `maxIterations` and fails). Built-in actions do this naturally
(e.g. Publish filters `status_not: "published"`).
This demo uses an `onSale` boolean on the Product model: `loadData` filters
`values.onSale_not: true`, and `processData` sets `onSale: true`. To re-run the discount
on a product, turn its **On sale** switch back off.
> Note the `values.` prefix in the filter. The bulk-action list path calls storage
> directly (bypassing the GraphQL where-transform), and at the storage layer custom
> fields live under `values.` while system fields (`id`, `status`, …) are top-level. A
> bare `onSale_not` throws `There is no field with the fieldId "onSale"`.
Flow:
```
[Admin UI] select products → "Apply -10%" button
│ worker.processInBulk({ action: "ApplyDiscount", where, data })
▼
[GraphQL] bulkActionProduct mutation → context.tasks.trigger(...)
▼
[Background task] list task paginates (loadData) → process task runs processData per entry
▼
[Result] each product's price reduced by 10%, progress visible in the Background Tasks screen
```
## Real-time notification
Once a product is discounted, the backend sends a websocket message to the user who
triggered the action (`WebsocketsSendToIdentityUseCase`), and the admin toasts it:
```
[processData] → sendToIdentity({ action: "cms.product.discountApplied", data: { id, price, percent } })
▼
[DiscountAppliedEventHandler] (WebsocketEventHandler) → notifications.success(...)
```
Mirrors the File Manager AI-enrichment pattern. Fires per processed entry, so toasts pop
live as the background task works through the batch.
## Post mapping
1. **Bulk actions** — select products, hit "Apply -10%", prices update. Mention: this
kicks off a background task (parts 2 & 3).
2. **Background tasks in code** — show `ApplyDiscountBulkAction.ts` (`loadData` /
`processData` _are_ the task body) and `ApplyDiscountAction.tsx` (`processInBulk` =
the trigger). Explain Webiny generates the task machinery.
3. **Background tasks interface** — show the run in the Background Tasks beta screen:
status, batches, done/failed counts.
## Running it
```bash
yarn webiny watch api --env dev # picks up the model + backend bulk action
yarn webiny watch admin --env dev # picks up the button
```
Then in Admin: create a few Products (with prices), select them, click **Apply -10%**.
## Note — public API added in 6.5.0
Authoring a custom bulk action from a project needs API surface that wasn't public
before 6.5.0. Exposed via the `webiny` meta-package (each declared in the owning
package's `src/exports/**` folder, which the `generate-webiny-package` script merges):
- **API** — `EntriesBulkAction` → `webiny/api/cms/entry`
- **Admin (trigger)** — `BulkActionFeature`, `BulkActionUseCase` → `webiny/admin/cms/entry/list`
- **Admin (UI)** — `BulkActionButton`, `useBulkActionDialog` → `webiny/admin`
`useModel`, `useContentEntriesPresenter`, and `useFeature` were already public.