Merge pull request #15 from taskbadger/sk/deprecate-task-actions

Deprecate per-task actions in docs

Author: snopoke

docs/actions.md

@@ -0,0 +1,97 @@
+---
+title: Actions
+---
+# Actions
+
+Actions are at the core of Task Badger's alerting. They let you send notifications and
+callouts based on task events — status changes, progress thresholds, or exceeding an
+expected runtime.
+
+Actions are configured in the Task Badger web UI and apply across your tasks, so you no
+longer need to attach alerting to individual tasks in your code.
+
+!!!note "Deprecation"
+    Attaching actions to individual tasks via the SDK, CLI, or API is **deprecated** and
+    will be removed in a future release. Configure actions in the web UI instead — see
+    [Migrating from per-task actions](#migrating-from-per-task-actions).
+
+## How actions work
+
+An action combines two things:
+
+- A **channel** — the reusable destination that delivers the notification (email, web hook).
+  Channels are configured once under **Integrations** and can be reused by many actions.
+- A **trigger** — the task event(s) that cause the action to fire.
+
+When a task reaches a trigger point, Task Badger runs the action's channel with the current
+task details.
+
+## Channels
+
+A channel is a reusable destination for notifications. See [Integrations](integrations.md)
+for the available channel types and how to configure them.
+
+## Creating an action
+
+Actions are created in the web UI under **Integrations → Global Actions**.
+
+Each action has the following settings:
+
+| Setting        | Description                                                                          |
+|----------------|--------------------------------------------------------------------------------------|
+| Name           | A label to identify the action.                                                      |
+| Project filter | Limit the action to a single project. Leave blank to apply to tasks in all projects. |
+| Name filter    | A regular expression matched against the task name. Leave blank to match all tasks.  |
+| Channel        | The [integration](integrations.md) used to deliver the notification.                 |
+| Trigger        | The task event(s) that fire the action — see [Triggers](#triggers).                  |
+
+Actions can be enabled or disabled at any time without deleting them.
+
+## Triggers
+
+A trigger is a comma-separated list of trigger points. Each trigger point is one of the following:
+
+* A numeric value which is matched against the task `value`.
+* A percentage value which is matched against the task `value_percent`.
+* A task status which is matched against the task `status`.
+* A special value `max_runtime_exceeded` which is matched when the task exceeds its `max_runtime` value.
+
+Numeric and percentage trigger points can also be prefixed with `*/` to indicate that the trigger should
+fire at regular intervals. For example, `*/50%` will fire at 0%, 50% and 100%.
+
+Examples:
+
+| Trigger               | Trigger Fire Points                                                          |
+|-----------------------|------------------------------------------------------------------------------|
+| `*/30%`               | When `value_percent` passes any multiple of 30%: 0%, 30%, 60%, 90%           |
+| `success,error,stale` | When the state changes to any of the listed states                           |
+| `95%,250,error`       | At 95%, when the value reaches or passes 250, when the state becomes `error` |
+
+### Trigger edge cases
+
+If a task value or status skips past multiple trigger points, only the last matching trigger will be
+executed.
+
+For example, an action configured with `20,40,80` whose value goes from `0` directly to `90` will
+skip over the `20` and `40` events and only fire the `80` event. This also applies to task
+status triggers.
+
+This also applies to multiple trigger points that are reached simultaneously, for example, let's say
+an action has the following trigger: `100,success`. It is quite likely that the task could reach
+both those states at the same time but the action will only fire once.
+
+## Migrating from per-task actions
+
+Previously, actions were attached to individual tasks when they were created — via the
+`actions` argument in the SDK, the `--action` option in the CLI, or the task `actions` field
+in the API. This approach is **deprecated**: existing per-task actions keep working for now,
+but the ability to create them will be removed in a future release.
+
+To migrate, recreate your alerting as global actions in the web UI:
+
+1. Configure the channels you need under **Integrations** (see [Integrations](integrations.md)).
+2. Under **Integrations → Global Actions**, create an action for each alert you want, using a
+   name filter and/or project filter to target the same tasks you previously attached actions to.
+
+Global actions replace per-task actions entirely — a single action with a name filter can cover
+every task that used to carry an inline action definition.

docs/api.md

@@ -20,6 +20,10 @@ task URL is:
 | Update task action  | `PATCH /api/{org}/{project}/tasks/{task_id}/actions/{action_id}/`                                                             |
 | Cancel task action  | `DELETE /api/{org}/{project}/tasks/{task_id}/actions/{action_id}/`                                                            |
 
+!!!note "Deprecation"
+    The endpoints for adding and updating task actions (as well as the `actions` field on the
+    create/update task endpoints) are **deprecated** and will be removed in a future release.
+    Configure [actions](actions.md) in the web UI instead.
 
 Full details of the API endpoints can be viewed at [https://taskbadger.net/api/docs/](https://taskbadger.net/api/docs/){:target="_blank"}
 

docs/cli.md

@@ -62,25 +62,10 @@ For more details on these commands run `taskbadger <command> --help`.
 
 ## Actions
 
-You can create actions for CLI tasks using the `--action` (`-a`) argument. The
-format for this argument is string with three components, separated by a space:
-
-```mermaid
-flowchart LR
-    trigger --- integration
-    integration --- config
-```
-
-The config parameter is a comma-separated list of key value pairs.
-
-Here is an example:
-
-```bash
-$ taskbadger run "demo task" --action error email to:me@test.com -- path/to/script.sh
-```
-
-If the task state becomes `stale` or `error`, use the `email` integration to
-send a notification to `me@test.com`.
+!!!note "Deprecation"
+    The `--action` (`-a`) argument for attaching actions to CLI tasks is **deprecated** and
+    will be removed in a future release. Configure [actions](actions.md) in the web UI instead.
+    Actions apply across your tasks, so you no longer need to attach them per command.
 
 ## Configuration
 

docs/data_model.md

@@ -51,7 +51,7 @@ The main attributes or a task are:
 
 `max_runtime`
 
-:   This value can be used in conjunction with task actions and monitors to trigger actions if a task
+:   This value can be used in conjunction with [actions](actions.md) and monitors to trigger alerts if a task
     exceeds its expected runtime. The value is in seconds.
 
 `stale_timeout`
@@ -201,64 +201,10 @@ modified again (with the potential exception of 'stale').
     to any other state via an update.
 
 
-## Task Actions
+## Actions
 
-Actions are at the core of Task Badger's secret sauce. They allow you to send notifications, perform callouts,
+Actions are at the core of Task Badger's alerting. They allow you to send notifications, perform callouts,
 and more based on task events.
 
-Every action specifies an [integration](integrations.md) e.g. `email`, and a trigger definition which is
-like a crontab expression, but for tasks. For example, `*/25%,success` means, "execute
-this action when the task value passes 25%, 50%, 75%, 100% and when the task status
-is set to `success`".
-
-A task may have multiple actions, each with their own integration and trigger definition.
-
-Here is an example of an action:
-
-```json
-{
-  "id": 640,
-  "task": "57ae8eVBrH7jbDgmYj6Ut2vR9S",
-  "trigger": "success,error",
-  "integration": "email",
-  "status": "active",
-  "config": {
-    "to": "me@example.com,you@example.com"
-  },
-  "created": "2022-11-16T07:10:30.551808Z",
-  "updated": "2022-11-16T07:10:30.551818Z"
-}
-```
-
-### Action Triggers
-
-An action trigger is a comma-separated list of trigger points. Each trigger point is one of the following:
-
-* A numeric value which is matched against the task `value`.
-* A percentage value which is matched against the task `value_percent`.
-* A task status which is matched against the task `status`.
-* A special value `max_runtime_exeeded` which is matched when the task exceeds its `max_runtime` value.
-
-Numeric and percentage trigger points can also be prefixed with `*/` to indicate that the trigger should
-fire at regular intervals. For example, `*/50%` will fire at 0%, 50% and 100%.
-
-Examples:
-
-| Trigger               | Trigger Fire Points                                                          |
-|-----------------------|------------------------------------------------------------------------------|
-| `*/30%`               | When `value_percent` passes any multiple of 30%: 0%, 30%, 60%, 90%           |
-| `success,error,stale` | When the state changes to any of the listed states                           |
-| `95%,250,error`       | At 95%, when the value reaches or passes 250, when the state becomes `error` | 
-
-### Action Edge cases
-
-If a task value or status skips past multiple trigger points, only the last matching trigger will be
-executed.
-
-For example, an action configured with `20,40,80` whose value goes from `0` directly to `90` will
-skip over the `20` and `40` events and only fire the `80` event. This also applies to task
-status triggers.
-
-This also applies to multiple trigger points that are reached simultaneously, for example, let's say
-an action has the following trigger: `100,success`. It is quite likely that the task could reach
-both those states at the same time but the action will only fire once.
+Actions are configured in the web UI and apply across your tasks. See [Actions](actions.md) for
+details on channels and triggers.

docs/index.md

@@ -49,13 +49,14 @@ taskbadger run "my task" -- ./script.sh
 
 - **Task tracking** — monitor status, progress, and metadata for any background job
 - **Celery integration** — automatic tracking of all Celery tasks with zero code changes
-- **Actions and triggers** — get notified via email, webhook, or other integrations on task events
+- **Actions and triggers** — get notified via email, webhook, or other integrations on task events, configured in the web UI
 - **CLI** — monitor shell commands without writing code
 
 ## Learn More
 
 - [Quick Start](quick.md) — full setup walkthrough
 - [Python SDK](python.md) — SDK reference
 - [CLI](cli.md) — command line usage
-- [Data Model](data_model.md) — task states, actions, and triggers
+- [Data Model](data_model.md) — task states and fields
+- [Actions](actions.md) — notifications and triggers
 - [API Endpoints](api.md) — REST API reference

docs/integrations.md

@@ -4,10 +4,11 @@ title: Integrations
 
 # Integrations
 
-Task Badger integrations are what power the actions. When an action is triggered it causes
-the specified integration to execute.
+Integrations are the channels that power [actions](actions.md). When an action is triggered
+it delivers a notification through the specified integration.
 
-Each action specifies the integration ID as well as a set of configuration used by the integration.
+Integrations are configured once in the web UI under **Integrations** and can be reused by
+many actions. Each integration has an ID which is used to reference it from an action.
 
 ## Email
 
@@ -21,76 +22,17 @@ Email a set of recipients with the current status of the task.
 |-----------|-----------------------------------------------------------|
 | `to`      | Comma-separated list of recipient email addresses. Max 5. |
 
-**Example Usage**
-
-=== "Python"
-
-    ```python
-    action = Action(
-        "success,error",
-        integration=EmailIntegration(to="me@example.com")
-    )
-    task = Task.create(name="task name", actions=[action])
-    ```
-
-=== "Cli"
-
-    ```shell
-    taskbadger run "demo task" --action error,sucess email to:me@test.com -- path/to/script.sh
-    ```
-
-=== "Shell"
-
-    ```shell
-    $ curl -X PATCH "https://taskbadger.net/api/${ORG}/${PROJECT}/tasks/" \
-      -H "Authorization: Bearer ${API_KEY}" \
-      -H "Content-Type: application/json" \
-      -d '{"name":"demo", "actions":[{"integration":"email","trigger":"success,error","config":{"to":"me@example.com"}}]}'
-    ```
-
 ## Web Hook
 
 The web hook integration allows you to call a URL with a task payload.
 
-For security reasons web hooks must first be created on the web UI before they can be used
-in task actions. This can be done by going to **Integrations** in the sidebar navigation.
-
-Each web hook will have its own unique ID which is what will be used when creating actions.
+Web hooks must first be created in the web UI, under **Integrations** in the sidebar
+navigation, before they can be used by an action.
 
 **Integration ID**: `webhook:<slug>`
 
 **Configuration**
 
-There is currently no additional configuration required for Web Hooks other than
-the configuration provided when creating them on the web.
-
-
-
-**Example Usage**
-
-=== "Python"
-
-    ```python
-    action = Action(
-        "success,error",
-        integration=WebhookIntegration(id="webhook:demo-123")
-    )
-    task = Task.create(name="task name", actions=[action])
-    ```
-
-=== "Cli"
-
-    Since no additional configuration is required we must pass an empty string:
-
-    ```shell
-    taskbadger run "demo task" --action error,sucess webhook:demo-123 "" -- path/to/script.sh
-    ```
-
-=== "Shell"
-
-    ```shell
-    $ curl -X PATCH "https://taskbadger.net/api/${ORG}/${PROJECT}/tasks/" \
-      -H "Authorization: Bearer ${API_KEY}" \
-      -H "Content-Type: application/json" \
-      -d '{"name":"demo", actions":[{"integration":"webhook:demo-test","trigger":"success,error","config":{}}]}'
-    ```
+There is currently no additional configuration required for web hooks other than
+the configuration provided when creating them in the web UI. Each web hook has its own
+unique ID (`webhook:<slug>`) which is used when referencing it from an action.

docs/python.md

@@ -49,20 +49,14 @@ The SDK provides a [Task](#taskbadger.Task) class which offers a convenient inte
 Tasks are created by calling the `Task.create` method:
 
 ```python
-from taskbadger import Task, Action, EmailIntegration
+from taskbadger import Task
 
-# create a new task with custom data and an action definition
+# create a new task with custom data and tags
 task = Task.create(
     "task name",
     data={
         "custom": "data"
     },
-    actions=[
-        Action(
-            trigger="*/10%,success,error",
-            integration=EmailIntegration(to="me@example.com")
-        )
-    ],
     tags={"tenant": "acme"}
 )
 ```
@@ -75,8 +69,7 @@ from taskbadger import Task
 task = Task.get(task_id)
 ```
 
-The task object provides methods for updating the properties of a task, adding custom data
-and adding actions.
+The task object provides methods for updating the properties of a task and adding custom data.
 
 ### Connection management