From 7e1b8656d5959ebc27b600c00f3f31e257d2d10d Mon Sep 17 00:00:00 2001 From: Dev Date: Wed, 28 Oct 2026 19:41:02 +0530 Subject: [PATCH] docs: add create, Show on alerts, Send test and API to Actions page --- opsimate-docs/docs/alerts/actions.md | 63 +++++++++++++++++++++++- opsimate-docs/docs/alerts/enrichments.md | 2 +- 2 files changed, 62 insertions(+), 3 deletions(-) diff --git a/opsimate-docs/docs/alerts/actions.md b/opsimate-docs/docs/alerts/actions.md index 1db00ea..f85aa10 100644 --- a/opsimate-docs/docs/alerts/actions.md +++ b/opsimate-docs/docs/alerts/actions.md @@ -6,8 +6,30 @@ sidebar_position: 5 An action is a configured integration (Slack webhook, Teams webhook, Jira, generic HTTP) that is fired against an Alert. -## Scope -Each action can be limited to certain alerts by name or criteria. +## Creating an action + +1. In the left sidebar, open **Actions**, then select **New action**. +2. Enter a **Name** and choose a **Type** (Slack, Teams, Jira or HTTP). +3. Fill in the **Configuration** for that type. See [Action types and what they need](#action-types-and-what-they-need). +4. Optionally, limit where the action is offered under **Show on alerts**. See [Show on alerts](#show-on-alerts). +5. Select **Send test** to check the configuration. See [Send test](#send-test). +6. Select **Create action**. + +On the Actions page, the pencil on a row edits that action. It opens the same dialog, and the button reads **Save changes**. The trash icon deletes the action after you confirm. + +## Show on alerts + +**Show on alerts** controls which alerts an action is offered on in the alert view. It has two kinds of criteria: + +| Criteria | How it matches | +| --- | --- | +| Alert name substrings | Any one substring may match. Matching is case-insensitive. | +| Label matcher groups | Any one group may match. Every matcher inside a group must match. | +| Name and labels together | Both must match: the name condition AND a label group. | + +**An action with no criteria shows on every alert.** The dialog says so: "Leave empty to show this action on every alert." On the Actions page, such an action shows **All alerts** in its **Applies to** column. + +This is not a permission. It only decides where the action is offered in the alert view. Mute policies and enrichments treat an empty rule the opposite way: with no criteria they match nothing. See [Match criteria](./enrichments.md#match-criteria). ## Action types and what they need @@ -33,6 +55,24 @@ With the switch on: In the API this is `config.fireAndForget: true` on an action of type `http`. +## Send test + +**Send test** runs the action with sample alert data and reports **Test succeeded** or **Test failed** with a message. Nothing is saved. The play button on each row of the Actions page runs the same test for an existing action. + +The sample alert has these values: + +| Field | Value | +| --- | --- | +| Name | `Test alert from OpsiMate` | +| ID | `test-alert-1` | +| Severity | `critical` | +| Service | `demo-service` | +| Tags | `env=prod`, `team=platform` | + +:::warning +A test is a real request. A Slack or Teams action posts a real message, and a Jira action creates a real issue. Point the action at a test channel or project first. +::: + ## Variable substitution in action payloads Templates use: `{{name}}` @@ -68,6 +108,25 @@ Tag values are available under three prefixes, all equivalent. Replace `env` wit ## Running an action from an alert In the alert details panel there's a collapsible Actions section (with a count). Expanding it shows a button per action. Clicking one opens a dialog. The dialog builds a preview, lets you edit the fields, and you hit Send. Success or failure appears as a notification. There's also a Manage link to the Actions page, and if nothing's configured you get a prompt to create one. +## API + +All routes are under `/api/v1/actions`. Every route needs a logged-in user or the API token (`x-api-token` header), as on the other API pages. + +| Method & path | What it does | +| --- | --- | +| `GET /` | List actions | +| `GET /:actionId` | Get one action (404 if missing) | +| `POST /` | Create: `name`, `type` (`slack`, `teams`, `jira`, `http`), `config`, optional `nameContainsAny`, `labelMatcherGroups` | +| `PUT /:actionId` | Replace the whole action (same body as create, not a partial update) | +| `DELETE /:actionId` | Delete | +| `POST /test` | Send a test with sample alert data. Same body as create, nothing is saved. Returns `data.ok` and `data.message` | +| `POST /:actionId/preview` | Render the action for an alert without sending it | +| `POST /:actionId/run` | Run it against an alert, with optional overrides | + +A logged-in Viewer gets `403` on every `POST`, `PUT` and `DELETE` above, including `test`, `preview` and `run`. + +The `config` fields for each type are the ones in the [types table](#action-types-and-what-they-need). + ## Alert History Timeline Each entry is labelled as Action run with a description line and the timestamp followed by who ran it. diff --git a/opsimate-docs/docs/alerts/enrichments.md b/opsimate-docs/docs/alerts/enrichments.md index 9172d63..ccb829a 100644 --- a/opsimate-docs/docs/alerts/enrichments.md +++ b/opsimate-docs/docs/alerts/enrichments.md @@ -96,7 +96,7 @@ An alert matches when its name matches any name criterion and at least one label Label equality compares the complete value and is case-sensitive. A label `contains` condition compares a substring case-insensitively. A missing label does not satisfy a matcher. An enrichment with no criteria matches nothing, so supply criteria or explicitly select **Apply to all alerts**. -These matcher rules are the same ones used by mute policies and actions, so a rule that works in one place behaves the same way in the others. +Name and label criteria match the same way for mute policies, enrichments and actions. The one difference is the case with no criteria: an action with no criteria shows on every alert, while a mute policy or enrichment with no criteria matches nothing. ## Effects