Version: 1.4 (Current)

Creating a policy

Route: /policies

See also: Overview · Conditions · Modifiers and tools

Above the table, page tabs Policies / All executions. On the Policies tab, segmented All, Basic, Recurring filter the list by trigger type (Recurring shows only scheduled triggers). Tip: right-click a policy to open its context menu and view available actions (same actions as the row buttons and bulk bar).

Create a policy

Open Management → Policies.

Click Create policy. A wizard opens in a large dialog with three steps across the top:

Step	Subtitle	What you set
General	Name, trigger and schedule	Enabled switch at the top, then name, priority, description, trigger, time window and, at the bottom, Permission (optional)
Conditions	Which alerts it applies to	The alert filters, in the builder or as TQL, with a live count of matching alerts
Actions	What it does to them	Modifiers, Extractions, and Run a tool, with a live preview of the changes

Fill in General and click Next. Fill in Conditions and click Next again.
Configure the Actions step and click Create.

Back returns to the previous step without losing anything. Cancel (or the close button) closes the wizard; see Saving and closing.

General step

Field	Description
Enabled / Disabled	Switch at the top of the step (stored as status `active` / `inactive`). A disabled policy is saved but never runs. Enabled policies outside their time window show Pending in the table
Name	Policy name (required)
Priority	Whole number, `0` or more (required). Lower numbers run first: `0` is the highest priority. Negative values are rejected by the form and by the API (400)
Description	Purpose and expected outcome (required)
Permission (optional)	Last field of the step. The field shows the full scope (`execute:policies:<suffix>`). Copy it into a role Permissions list. Empty = no extra check beyond normal policy permissions
Trigger	When the policy runs — event-based or scheduled (see below) (required)
Time Range	All Day / Time Range. A new policy is All Day by default; with Time Range, set the start and end times between which the policy is eligible

Next checks the required fields (Name, Description, Priority, Trigger) and stays on General with "Form data is invalid or incomplete" while one of them is empty.

Permission (optional scope)

Use Permission when only some operators should see or change a given policy:

Situation	Effect
Permission empty	Normal read:policies / write:policies / run:policies / admin:policies apply. Manual Run still also needs write:alerts (`admin:alerts` or global admin count) — write:policies does not imply run
Permission set	Interactive view, edit, delete, and Run (preview + apply) also require the exact `execute:policies:<suffix>` on the user’s role (or admin:policies / global admin). Unsuffixed execute:policies, write:policies, run:policies, and being the policy author do not open that policy. Run and the custom execute scopes also need write:alerts
Automatic pipeline	Scheduled and on-alert runs still apply the policy; they do not require the user’s custom execute scope
Custom tool on Run a tool	Independent — policy Permission is not the same as a tool’s Permission (`execute:tool:…`)

Placeholder example in the form: execute:policies:my_scope. The product stores the suffix; the UI always shows the full execute:policies:… string (with a copy control). After you save, the value appears in the roles Permissions dropdown for administrators to grant.

Trigger

Trigger	When it runs
On alert creation and any change type	Whenever a new alert arrives or an existing alert changes
Every x minutes	On a fixed minute interval (Every (minutes) — minimum 1)
Daily at fixed time	Once per day at Time (24-hour `HH:mm`)
Weekly at fixed time	On the selected weekday and Time
Monthly at a fixed time	On Day of the month (Day 1–31 or Last Day of Month) and Time

Scheduled triggers still respect the Conditions step: only alerts matching your filters are modified on each run. With empty conditions, all open alerts qualify (subject to the active time window). Conditions on Open for / Silent for or on relative dates (now-1d) are re-evaluated on every run, so alerts qualify as they age — see Conditions — Relative time.

Help text shown in the form:

Daily: "Policy will run daily at this time (24-hour format)"
Weekly: "Policy will run weekly on this day and time"
Monthly: reuses the notification monthly hint ("Notification will be sent monthly on this day and time")

Conditions step

The left side holds the conditions; the right side, the Matching alerts panel. A How conditions work link opens the Conditions page.

Builder / TQL switch — write the conditions with the visual builder or as a TQL query. The policy is always stored as builder conditions; TQL that cannot be converted exactly is rejected. See Conditions — Builder and TQL.
Matching alerts — the number of open alerts that currently meet the conditions and a sample of them, refreshed as you edit. See Conditions — Matching alerts.
Next stays on this step while a filter is incomplete, AND and OR are mixed in one group, or the TQL is invalid; the reason is shown under the conditions.

A policy without conditions applies to every alert

With no conditions, a banner This policy has no conditions appears on the Conditions and Actions steps. With trigger On alert creation and any change type it reads "Without conditions it will be applied to every incoming alert."; with a scheduled trigger, "Without conditions every scheduled run will be applied to all open alerts." You can still save the policy — the banner is a reminder, not an error.

Actions step

The Actions step opens once Conditions is valid. It has three tabs on the left and the Preview of changes panel on the right.

Tab	What it does	Reference
Modifiers	Change fields of each matching alert (Modify field), move its severity (Severity step), mark it as an effect (Mark as effect), or relate resources (Resource relation). Click Add modifier for each row; rows apply in list order	Modifiers and tools
Extractions	Copy part of a field into a custom attribute with a regular expression. Click Add extraction for each row: Attribute, Regex, Target attribute	Modifiers and tools — Extractions
Run a tool	Execute custom tool: None or a registered tool, run on every matching alert after modifiers and extractions	Modifiers and tools — Execute custom tool

A policy can have no actions at all, only modifiers, only extractions, only a tool, or any combination. When it runs, the engine applies them in this order:

Modifiers (in list order)
Extractions (in list order)
The custom tool, if one is selected

Modifier types at a glance

Modify field — Select column (and Enter attribute when the column is attributes), Select operation (set, add, delete, replace, or a text transform upper, lower, capitalize, trim) and the value. See Text transforms.
Severity step — Step (-10 to 10, not 0), optional Never above (shown when the step is positive) or Never below (shown when it is negative). See Severity step.
Mark as effect — Cause is Conditions or Open alert on a parent resource, then Window, Unit, Direction. See Mark as effect.
Resource relation — Source Value, Topology, or Graph, and Overwrite existing parent. See Resource relation.

Extractions tab

Each extraction reads an alert field (Attribute), applies a Regex, and stores the first capture group (or the whole match) in the custom attribute named in Target attribute. Extractions have no conditions of their own — the policy Conditions decide which alerts they touch. Full behavior, validation, and examples: Modifiers and tools — Extractions.

Extractions are part of the policy — they use the same policy permissions (read:policies / write:policies / …). There is no separate Extractions menu or *:extractions scopes.

Preview of changes

The right-hand panel shows what the modifiers and extractions would change on the open alerts that match the conditions — nothing is saved and no alert is written. It refreshes a moment after each edit.

The tag at the top reads X of Y alerts would change: Y is the number of matching alerts evaluated (the most recently updated ones, up to 1,000) and X how many of them at least one action would change.
The table lists matching alerts (alerts with changes first) with Resource / event and Changes: one line per field, field: before → after — for example severity: minor → major or attributes.hostname: — → web-01. An alert that nothing would change shows No changes.
When more alerts match than the panel shows, it says Showing the first N of M alerts. (the panel loads up to 50).
Tools are not run in the preview. A selected tool never runs from the wizard, and its effect is not shown.
Rows that are not complete yet — a modifier without an operation or value, an extraction without a regex or with an invalid one — are left out of the preview, with a warning such as "1 incomplete action is not included in the preview."
Mark as effect is not previewed (linking needs the cause alerts and their creation times); Resource relation shows resourceParent and the resourceChildren it would add.
If the draft is rejected by the server, the panel shows "The preview could not be calculated: …" with the reason.

The preview uses the same calculation as Run → Review matched alerts, but on the unsaved draft. For an on-receive policy it shows the effect on alerts that are already open; incoming alerts will be treated the same way.

Saving and closing

Create policy: steps unlock in order. Next validates the current step; Create appears on the Actions step.
Edit policy (click a name, double-click a row, or Edit): every step is reachable from the start. Click a step title to jump to it — a step can be opened when the steps before it are valid. Update is available on any step as long as all three steps are valid. A step with an error is marked in red in the step bar.
On save, the wizard validates all steps again and, if one fails, opens that step (and, on Actions, the Modifiers or Extractions tab with the problem).
Closing the wizard with unsaved changes asks "Discard unsaved changes?" — "You have unsaved changes. Do you want to discard them?" — with Discard and Cancel. TQL with an error always counts as an unsaved change.
Escape and a click outside the dialog do not close the wizard, so a stray key does not lose the work; use Cancel or the close button.

Computed status in the table

UI status	Meaning
Active	Policy active and within time window (or All Day)
Pending	Active but outside configured Time Range
Inactive	Policy disabled

Table columns

Column	Description
Name	Policy name (click to edit)
Description	Description
Status	Active / Pending / Inactive
Priority	Numeric priority
Permission	Full `execute:policies:…` scope when set, or - when unset
Modifier	Count of modifiers on the policy
Time Range	ALL DAY or start–end times
Tool \| Tools	Assigned custom tool name, or N/A
Creation date	When the policy was created

Double-click a row to open the policy wizard in edit mode. Use the search box and the TQL ON / TQL OFF tag for advanced queries — see TQL search and filters.

For sorting, Column manager, pagination, and bulk actions, see List tables and bulk actions.

Bulk and row actions

Action	Scope	Notes
Run	Exactly 1 selected row	Opens Review matched alerts, then Confirm and apply
Edit	1 row	Opens the policy wizard
Duplicate	≥ 1 row	Copies with a new name
Enable / Disable	≥ 1 row	Toggle Status
Delete	≥ 1 row	Requires delete permission; confirmation dialog

Row shortcuts (with permission): green Run, blue Edit, red Delete.

Run policy — review then results

After Run, a drawer titled Review matched alerts lists alerts that match but have not been changed yet. Toggle Show only alerts that will be modified. Click Confirm and apply to execute; then Policy execution results shows:

Section	Content
Summary	Policy Name, Alerts Matched, Alerts Modified
Affected Alerts (showing first 20)	Table: ID, Resource, Event, Severity, Status
Errors	Per-alert error messages, if any

Row action View execution history opens the per-policy history drawer (not the All executions tab). The drawer follows read:policies; the global tab needs read:policies_history or read:policies_all_history.

Use Run to validate conditions, modifiers, and extractions on the saved policy before relying on it in production (the wizard preview already shows the effect while you edit). Manual Run needs run:policies and also write:alerts (admin:alerts or global admin count); write:policies alone is not enough.

API: preview a draft policy

The wizard panels call POST /api/policies/preview. Integrations can use it to check a policy before creating it with POST /api/policy.


Method / path	`POST /api/policies/preview`
Scope	write:policies
Query	`limit` — alerts returned in `alerts`, `1`–`200` (default `50`)
Body	The draft policy, same JSON as when creating one: `conditions`, `modifiers`, `extractions`, `trigger`, `triggerConfig`. `name` and `description` are optional here; `customTool` is ignored

It only reads: no alert is written, no execution is recorded, and no tool runs. Only open alerts are considered (not closed, expired, or deleted).

Example request:

curl -X POST "https://tobealert.example.com/api/policies/preview?limit=20" \
  -H "Authorization: Key $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": {"operator": "AND", "clauses": [{"key": "event", "op": "=", "value": "HostDown"}]},
    "modifiers": [{"column": "severity", "operation": "set", "value": "critical"}],
    "extractions": [{"attribute": "text", "regex": "host=(\\S+)", "targetAttribute": "hostname"}],
    "trigger": "alert"
  }'

Response:

Field	Description
`matchedCount`	Open alerts that match the conditions
`shownCount`	Alerts returned in `alerts` (at most `limit`)
`evaluatedCount`	Matching alerts on which the actions were evaluated — the most recently updated ones, up to 1,000
`wouldModifyCount`	How many of the evaluated alerts at least one modifier or extraction would change
`matchesAll`	`true` when the draft has no conditions (every open alert matches)
`alerts[]`	`id`, `resource`, `event`, `severity`, `status`, `environment`, `text`, `previewChanges`, `wouldModify`

previewChanges maps each field that would change to { "from": …, "to": … } — for example {"severity": {"from": "minor", "to": "critical"}, "attributes.hostname": {"from": null, "to": "web-01"}} — and wouldModify is true when it is not empty.

{
  "status": "ok",
  "matchedCount": 134,
  "shownCount": 20,
  "evaluatedCount": 134,
  "wouldModifyCount": 97,
  "matchesAll": false,
  "alerts": [
    {
      "id": "6f1c…",
      "resource": "esx-01",
      "event": "HostDown",
      "severity": "major",
      "status": "open",
      "environment": "Production",
      "text": "Host unreachable host=esx-01.dc1",
      "previewChanges": {
        "severity": { "from": "major", "to": "critical" },
        "attributes.hostname": { "from": null, "to": "esx-01.dc1" }
      },
      "wouldModify": true
    }
  ]
}

A draft that is not valid — an unknown modifier column or operation, invalid conditions, an extraction without regex or with an invalid one, a targetAttribute with . or $ — returns 400 with the reason in message, the same check as when saving.

Best practices

Set Trigger on General before fine-tuning Conditions and Actions; leave All Day unless the policy must only act during part of the day.
Watch Matching alerts while you write the conditions: a count close to all open alerts usually means a filter is missing.
Check Preview of changes before saving; for tools, test them separately (Test tool in the tool editor) since the preview does not run them.
Use On alert creation and any change type for real-time enrichment; use scheduled triggers for batch cleanup.
Run after every significant change and check Alerts Modified matches expectations (modifiers and extractions both count as changes).
Disable policies (Status → inactive) instead of deleting when you need a temporary pause.
Set Permission only for sensitive policies, then grant the matching execute:policies:<suffix> on the roles that should manage or Run them — see Permissions reference — Policies.

Create a policy​

General step​

Permission (optional scope)​

Trigger​

Conditions step​

Actions step​

Modifier types at a glance​

Extractions tab​

Preview of changes​

Saving and closing​

Computed status in the table​

Table columns​

Bulk and row actions​

Run policy — review then results​

API: preview a draft policy​

Best practices​