Add notification documentation

.vale/styles/config/vocabularies/DependencyTrack/accept.txt

@@ -78,6 +78,7 @@ Webex
 [Cc]onfig
 [Cc]onfigs
 [Cc]ron
+[Cc]rontab
 [Dd]atacenter
 [Dd]atasource
 [Dd]atasources
@@ -94,8 +95,11 @@ Webex
 [Jj]etstack
 [Kk]enna
 [Ll]iveness
+[Ll]oopback
 [Ll]ookups
 [Mm]icroservices
+[Mm]isconfiguration
+[Mm]isconfigured
 [Mm]ixeway
 [Nn]amespace
 [Nn]amespaces
@@ -135,5 +139,6 @@ timestamptz
 truststore
 truststore
 [Tt]yposquatting
+walkthrough
 walkthroughs
 zstd

AGENTS.md

@@ -67,3 +67,4 @@ Some reference pages are generated from source repositories. Do not edit these f
 - No line length limit for Markdown prose.
 - YAML indentation: 2 spaces, no document-start markers.
 - Vale enforces Google developer style and write-good rules. Accepted/rejected terms are in `.vale/styles/config/vocabularies/DependencyTrack/`.
+- Page-specific images mirror the docs tree under `docs/assets/images/`: an image used by `docs/<section>/<page>.md` lives at `docs/assets/images/<section>/<page>/<name>.<ext>`. Shared assets (e.g. `logo.svg`) stay at the root of `docs/assets/images/`.

context/vocabulary.md

@@ -65,7 +65,8 @@ Use these terms consistently. Avoid synonyms not listed here.
 - **notification group** — Event type classification (e.g., NEW_VULNERABILITY, POLICY_VIOLATION, BOM_PROCESSED, BOM_PROCESSING_FAILED).
 - **notification level** — *Informational*, *Warning*, or *Error*. Higher levels include lower.
 - **alert** — A routing rule that subscribes to notification groups and delivers to a publisher. Called "notification rule" in the API; prefer "alert" in docs.
-- **publisher** — Delivery mechanism: email, Slack, Teams, Mattermost, Jira, webhook.
+- **publisher** — Delivery mechanism: email, Slack, Teams, Mattermost, Jira, webhook. Fixed set; operators configure global settings but cannot create, clone, or delete publishers.
+- **notification template** — User-managed Pebble template + MIME type bound to a publisher. UI label is "Notification templates". Each built-in publisher ships with a read-only default template; custom templates are created by cloning a default and editing the clone.
 
 ## Access control
 

docs/concepts/architecture/design/notifications.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-The notification system is responsible for informing users and external systems about events
+The notification system informs users and external systems about events
 occurring in the platform. It consists of three phases:
 
 1. **Emission**: Writing notifications to an outbox table
@@ -42,8 +42,8 @@ in the critical path.
 
 ## Emission
 
-Notifications are emitted by inserting records into the `NOTIFICATION_OUTBOX` table.
-This can happen within the same database transaction that performs the business logic
+Domain logic emits notifications by inserting records into the `NOTIFICATION_OUTBOX` table.
+The insert can happen within the same database transaction that runs the business logic
 triggering the notification, thus avoiding the [dual write problem].
 
 ```mermaid
@@ -60,15 +60,15 @@ erDiagram
 
 The `ID` column uses [UUIDv7], which combines global uniqueness with sortability.
 The `PAYLOAD` column contains the serialized notification in [Protobuf] format.
-Its schema is documented in the [notification schema reference](../../../reference/schemas/notification.md).
+The [notification schema reference](../../../reference/schemas/notification.md) describes the schema.
 
 ### Preliminary filtering
 
-To reduce load on the outbox table, notifications are only inserted if *at least one*
-enabled alert could *potentially* match them. This check is performed during
-the `INSERT` operation using an `EXISTS` subquery against the `NOTIFICATIONRULE` table.
+To reduce load on the outbox table, the system only inserts a notification if *at least one*
+enabled alert could *potentially* match it. The `INSERT` operation runs this check
+using an `EXISTS` subquery against the `NOTIFICATIONRULE` table.
 
-Notifications that have no matching rules are discarded immediately.
+Notifications that have no matching rules drop immediately.
 
 ## Relay
 
@@ -102,11 +102,11 @@ sequenceDiagram
 
 ### Concurrency control
 
-Transaction-level [advisory locks] prevent concurrent relay cycles across multiple API server instances.
-This ensures notifications are relayed in approximately the order they were emitted.
-The lack of concurrency is offset by batch processing. The batch size is configurable
-via [`dt.notification.outbox-relay.batch-size`](../../../reference/configuration/properties.md#dtnotificationoutbox-relaybatch-size)
-and defaults to 100.
+Transaction-level [advisory locks] prevent concurrent relay cycles across API server instances.
+This ensures the relay processes notifications in approximately the order the system emitted them.
+Batch processing offsets the lack of concurrency. Operators configure the batch size
+via [`dt.notification.outbox-relay.batch-size`](../../../reference/configuration/properties.md#dtnotificationoutbox-relaybatch-size);
+the default is 100.
 
 ### Routing
 
@@ -117,23 +117,23 @@ A rule matches if:
 * Its scope matches the notification's scope
 * Its level is equal to or less verbose than the notification's level
 * The notification's group is in the rule's configured groups
-* If the rule is limited to specific projects or tags, the notification's subject matches
+* If the rule limits delivery to specific projects or tags, the notification's subject matches
 
-Routing is performed in batches, using a single SQL query with `UNNEST`,
+The router runs in batches, using a single SQL query with `UNNEST`,
 reducing database round trips.
 
 ### Large notification handling
 
-Notifications exceeding a configurable size threshold (default: 64KiB) are offloaded to
-file storage, rather than being passed directly to the durable execution engine. This prevents large payloads
+Notifications exceeding a configurable size threshold (default: 64KiB) move to
+file storage instead of passing directly to the durable execution engine. This prevents large payloads
 (for example, `PROJECT_VULN_ANALYSIS_COMPLETED`) from bloating the workflow history.
 The publishing workflow retrieves the notification from file storage
 and deletes the file upon completion.
 
 ## Publishing
 
-For each notification with *at least one* matched rule, a *Publish Notification* workflow
-is scheduled. The workflow coordinates delivery for all matched rules.
+For each notification with *at least one* matched rule, the relay schedules a
+*Publish Notification* workflow. The workflow coordinates delivery for all matched rules.
 
 ```mermaid
 ---
@@ -159,12 +159,12 @@ sequenceDiagram
     deactivate W
 ```
 
-Publishing for each rule is performed by a separate activity concurrently,
+A separate activity publishes each rule concurrently,
 allowing independent retries per rule. If delivery to one destination fails,
 it does not affect delivery to others.
 
-A workflow is considered successful if *at least one* rule's publishing succeeded.
-Conversely, if publishing for *all* rules failed, the entire workflow is marked as failed.
+A workflow succeeds if *at least one* rule's publishing succeeded.
+Conversely, if publishing for *all* rules failed, the entire workflow fails.
 
 ### Publishers
 

docs/concepts/notifications.md

@@ -2,85 +2,104 @@
 
 ## Introduction
 
-Dependency-Track includes a robust and configurable notification framework,
-capable of alerting users or systems about the occurrences of various events
-in the platform.
+Dependency-Track includes a configurable notification framework
+that alerts users and external systems about events in the platform.
 
 ## Alerts
 
-Alerts, a.k.a. *notification rules*, are configurations that specify which notifications
-are sent to which destinations. An alert defines the scope, groups, and level of notifications
-it is interested in, and optionally restricts matching to specific projects or tags.
+Alerts, or *notification rules*, are configurations that specify which notifications
+go to which destinations. An alert defines the scope, groups, and level of notifications
+it subscribes to, and optionally restricts matching to specific projects or tags.
 
-Alerts can further be refined with a *filter expression*, written in [CEL], that evaluates
-against the content of each notification. This allows filtering by properties such as
-vulnerability severity, CVSS score, or component name, without requiring dedicated UI controls
+A *filter expression*, written in [CEL], can refine an alert further. The expression evaluates
+against the content of each notification, which lets you filter by properties such as
+vulnerability severity, CVSS score, or component name without dedicated UI controls
 for each filter criterion. Refer to [Filter expressions](../reference/notifications/filter-expressions.md)
 for details.
 
 ## Publishers
 
-Publishers are software components that send notifications emitted by the platform
-to a destination system. Dependency-Track supports multiple publishers, ranging from
+Publishers are software components that deliver notifications emitted by the platform
+to a destination system. Dependency-Track ships a range of publishers, from
 email to Webhook. Refer to [Publishers](../reference/notifications/publishers.md) for details.
 
 ## Templates
 
-Templates define how the platform-internal representation of notifications
-(see [Notification schema](../reference/schemas/notification.md)) is transformed
-to match the expectation of notification recipients.
+Templates define how the platform's internal representation of notifications
+(see [Notification schema](../reference/schemas/notification.md)) maps
+to the format that notification recipients expect.
 
-While each [publisher](#publishers) ships with a default template, administrators
-can also configure custom templates.
+Each [publisher](#publishers) ships with a default template, and administrators
+can configure custom templates. Refer to
+[Templating](../reference/notifications/templating.md) for the variables and
+filters available to templates.
 
 ## Levels
 
-Notifications can have one of three possible levels:
+Notifications can have one of three levels:
 
 * Informational
 * Warning
 * Error
 
-These levels behave similar to logging levels, in that they allow [alerts](#alerts)
-to define the verbosity of notifications being sent:
+These levels behave like logging levels, letting [alerts](#alerts)
+define the verbosity of outbound notifications:
 
-* Configuring an alert for level *Informational* will match notifications of level *Informational*, *Warning*, and *Error*.
-* Configuring an alert for level *Warning* will match notifications of level *Warning* and *Error*.
-* Configuring an alert for level *Error* will only match notifications of level *Error*.
+* An alert configured for level *Informational* matches notifications of level *Informational*, *Warning*, and *Error*.
+* An alert configured for level *Warning* matches notifications of level *Warning* and *Error*.
+* An alert configured for level *Error* matches only notifications of level *Error*.
 
 ## Scopes
 
-Notifications are emitted for different *scopes*. A scope broadly categorises the *subject*
+Notifications carry a *scope*. A scope broadly categorises the *subject*
 of a notification.
 
-* **SYSTEM**: Informs about system-level events, such as users being created, or integrations failing.
-* **PORTFOLIO**: Informs about portfolio-level events, such as BOM uploads, or newly identified vulnerabilities.
+* **SYSTEM**: Informs about system-level events, such as user creation or integration failures.
+* **PORTFOLIO**: Informs about portfolio-level events, such as BOM uploads or newly identified vulnerabilities.
 
 ## Groups
 
 A group is a granular classification of notification subjects within a [scope](#scopes).
 For example, the `NEW_VULNERABILITY` group within the `PORTFOLIO` scope identifies notifications
-emitted whenever a new vulnerability is found.
+that the system emits whenever it finds a new vulnerability.
 
 Refer to [Notification groups](../reference/notifications/groups.md) for the full list
 of groups, their scopes, levels, and triggers.
 
 ## Triggers
 
-Notifications are produced via one of two triggers:
+The platform produces notifications via one of two triggers:
 
-| Trigger  | Description                                                 |
-|:---------|:------------------------------------------------------------|
-| Event    | An event is emitted by the system under certain conditions. |
-| Schedule | The notification is sent based on a planned schedule.       |
+| Trigger  | Description                                                |
+|:---------|:-----------------------------------------------------------|
+| Event    | The system emits an event under certain conditions.        |
+| Schedule | The notification fires on a planned schedule.              |
 
-* Notifications triggered by events are ideal for near real-time automation,
-  and integrations into chat platforms.
-* Notifications triggered on a schedule are typically used to communicate high-level summaries,
-  and are thus a better fit for reporting purposes.
+* Event-triggered notifications fit near real-time automation
+  and chat-platform integrations.
+* Scheduled notifications typically communicate high-level summaries,
+  which makes them a better fit for reporting.
 
-Each [group](#groups) supports exactly one trigger type. Most groups are event-triggered;
+Each [group](#groups) supports exactly one trigger type. Most groups use event triggers;
 the summary groups (`NEW_VULNERABILITIES_SUMMARY`, `NEW_POLICY_VIOLATIONS_SUMMARY`)
-are schedule-triggered.
+use schedule triggers.
+
+## How alert filtering works
+
+When the platform dispatches a notification, it applies the alert's filters in this order:
+
+1. Scope, group, and level matching.
+2. Project and tag restrictions, if the alert limits delivery to specific projects or tags.
+3. The [filter expression](../reference/notifications/filter-expressions.md), if the alert has one.
+
+The platform runs the filter expression only after a notification has passed the preceding checks.
+Project and tag restrictions thus always apply, regardless of what the expression
+contains.
+
+Filter expressions are *fail-open*: if an expression fails to run at dispatch time, for
+example because it accesses a field that does not exist on the subject, the alert matches the
+notification anyway. This avoids silently suppressing notifications when an expression
+breaks. Evaluation failures appear in the logs as warnings; an alert with an expression that
+consistently fails behaves as though it has no filter expression at all.
 
 [CEL]: https://cel.dev/

docs/concepts/time-series-metrics.md

@@ -66,7 +66,7 @@ partitions for upcoming days. Administrators change the value at runtime,
 through the frontend or the REST API, rather than via a static startup
 property.
 
-![Retention setting under Administration > Configuration > Maintenance](../assets/images/admin_maintenance-config.png)
+![Retention setting under Administration > Configuration > Maintenance](../assets/images/concepts/time-series-metrics/admin-maintenance-config.png)
 
 Two consequences fall out of the design: shrinking retention reclaims disk
 on the next maintenance cycle, and extending retention only affects data

docs/guides/administration/.pages

@@ -6,6 +6,8 @@ nav:
   - configuring-ldap.md
   - configuring-oidc.md
   - configuring-internal-ca.md
+  - managing-notification-templates.md
+  - debugging-notifications.md
   - configuring-secret-management.md
   - scaling.md
   - migrating-from-v4.md

docs/guides/administration/configuring-database.md

@@ -82,7 +82,7 @@ They will know your organisation's best practices and can guide you in adjusting
 If you're not as lucky, we can wholeheartedly recommend [PGTune]. Given a bit of basic info about your system,
 it will provide a sensible baseline configuration. For the *DB Type* option, select `Online transaction processing system`.
 
-![Example output of PGTune](../../images/operations_database_pgtune.png)
+![Example output of PGTune](../../assets/images/guides/administration/configuring-database/pgtune-output.png)
 
 The `postgresql.conf` is usually located at `/var/lib/postgresql/data/postgresql.conf`.
 Most of these settings require a restart of the application.