IncidentHistory: cast type and relate notification history

Replaces the string comparisons in `IncidentHistoryRenderer` with the new
`IncidentHistoryType` enum and describes unnamed escalations by their
condition.

Co-Authored-By: Sukhwinder Dhillon <sukhwinder.dhillon@icinga.com>

Author: 2 people

library/Notifications/Common/Icons.php

@@ -5,6 +5,11 @@
 
 namespace Icinga\Module\Notifications\Common;
 
+use Icinga\Module\Notifications\Widget\IconBall;
+use ipl\Orm\Exception\ValueConversionException;
+use UnhandledMatchError;
+use UnitEnum;
+
 final class Icons
 {
     private function __construct()
@@ -58,4 +63,30 @@ private function __construct()
     public const MUTE = 'volume-xmark';
 
     public const UNMUTE = 'volume-high';
+
+    public const CONTACTGROUP = 'users';
+
+    public const SCHEDULE = 'calendar';
+
+    /**
+     * Get the icon for the given enum
+     *
+     * @param UnitEnum $enum
+     *
+     * @return IconBall
+     *
+     * @throws UnhandledMatchError If no icon is known for the given enum
+     */
+    public static function forEnum(UnitEnum $enum): IconBall
+    {
+        return new IconBall(match ($enum) {
+            IncidentHistoryType::OPENED => Icons::OPENED,
+            IncidentHistoryType::MUTED => Icons::MUTE,
+            IncidentHistoryType::UNMUTED => Icons::UNMUTE,
+            IncidentHistoryType::CLOSED => Icons::CLOSED,
+            IncidentHistoryType::RULE_MATCHED => Icons::RULE_MATCHED,
+            IncidentHistoryType::ESCALATION_TRIGGERED => Icons::TRIGGERED,
+            IncidentHistoryType::NOTIFIED => Icons::NOTIFIED
+        });
+    }
 }

library/Notifications/Common/IncidentHistoryType.php

@@ -0,0 +1,55 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 Icinga GmbH <https://icinga.com>
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+namespace Icinga\Module\Notifications\Common;
+
+/**
+ * Incident history entry types
+ *
+ * Each case maps to the backing string stored in the `type` column of the `incident_history` table.
+ * Register {@see \ipl\Orm\Behavior\EnumCast} on a model to have those columns hydrated automatically as enum instances.
+ */
+enum IncidentHistoryType: string
+{
+    case INCIDENT_SEVERITY_CHANGED = 'incident_severity_changed';
+    case ESCALATION_TRIGGERED = 'escalation_triggered';
+    case CLOSED = 'closed';
+    case OPENED = 'opened';
+    case MUTED = 'muted';
+    case UNMUTED = 'unmuted';
+    case RECIPIENT_ROLE_CHANGED = 'recipient_role_changed';
+    case NOTIFIED = 'notified';
+    case RULE_MATCHED = 'rule_matched';
+
+    /**
+     * Get the backing string value
+     *
+     * @return string
+     */
+    public function getValue(): string
+    {
+        return $this->value;
+    }
+
+    /**
+     * Get the translated label
+     *
+     * @return string
+     */
+    public function getLabel(): string
+    {
+        return match ($this) {
+            self::OPENED                        => t('Incident opened'),
+            self::INCIDENT_SEVERITY_CHANGED     => t('Incident severity changed'),
+            self::ESCALATION_TRIGGERED          => t('Escalation triggered'),
+            self::MUTED                         => t('Incident muted'),
+            self::UNMUTED                       => t('Incident unmuted'),
+            self::CLOSED                        => t('Incident closed'),
+            self::RECIPIENT_ROLE_CHANGED        => t('Recipient role changed'),
+            self::NOTIFIED                      => t('Notified'),
+            self::RULE_MATCHED                  => t('Rule matched')
+        };
+    }
+}

library/Notifications/Model/IncidentHistory.php

@@ -6,7 +6,9 @@
 namespace Icinga\Module\Notifications\Model;
 
 use DateTime;
+use Icinga\Module\Notifications\Common\Collection;
 use Icinga\Module\Notifications\Common\Database;
+use Icinga\Module\Notifications\Common\IncidentHistoryType;
 use Icinga\Module\Notifications\Common\Model;
 use Icinga\Module\Notifications\Common\Severity;
 use ipl\Orm\Behavior\EnumCast;
@@ -25,7 +27,7 @@
  * @property ?int $rule_id
  * @property ?int $rule_escalation_id
  * @property DateTime $time
- * @property string $type
+ * @property IncidentHistoryType $type
  * @property ?int $contact_id
  * @property ?int $schedule_id
  * @property ?int $contactgroup_id
@@ -37,6 +39,7 @@
  * @property ?string $message
  * @property ?string $notification_state
  * @property ?DateTime $sent_at
+ * @property ?string $event_id
  *
  * @property Query<Incident>|Incident $incident
  * @property Query<Contact>|Contact $contact
@@ -45,6 +48,7 @@
  * @property Query<Rule>|Rule $rule
  * @property Query<RuleEscalation>|RuleEscalation $rule_escalation
  * @property Query<Channel>|Channel $channel
+ * @property Query<NotificationHistory>|Collection<NotificationHistory> $notification_history
  */
 class IncidentHistory extends Model
 {
@@ -76,7 +80,8 @@ public function getColumns(): array
             'old_recipient_role',
             'message',
             'notification_state',
-            'sent_at'
+            'sent_at',
+            'event_id'
         ];
     }
 
@@ -103,6 +108,7 @@ public function createBehaviors(Behaviors $behaviors): void
     {
         $behaviors->add(new MillisecondTimestamp(['time', 'sent_at']));
         $behaviors->add(new EnumCast(Severity::class, ['new_severity', 'old_severity']));
+        $behaviors->add(new EnumCast(IncidentHistoryType::class, ['type']));
     }
 
     public function getDefaultSort(): array
@@ -133,6 +139,7 @@ public function createRelations(Relations $relations): void
         $relations->belongsTo('rule', Rule::class)->setJoinType('LEFT');
         $relations->belongsTo('rule_escalation', RuleEscalation::class)->setJoinType('LEFT');
         $relations->belongsTo('channel', Channel::class)->setJoinType('LEFT');
+        $relations->hasMany('notification_history', NotificationHistory::class)->setJoinType('LEFT');
     }
 
     /**

library/Notifications/View/IncidentHistoryRenderer.php

@@ -6,6 +6,7 @@
 namespace Icinga\Module\Notifications\View;
 
 use Icinga\Module\Notifications\Common\Icons;
+use Icinga\Module\Notifications\Common\IncidentHistoryType;
 use Icinga\Module\Notifications\Model\IncidentHistory;
 use Icinga\Module\Notifications\Widget\IconBall;
 use ipl\Html\Attributes;
@@ -17,6 +18,7 @@
 use ipl\I18n\Translation;
 use ipl\Web\Common\ItemRenderer;
 use ipl\Web\Widget\TimeAgo;
+use UnhandledMatchError;
 
 /** @implements ItemRenderer<IncidentHistory> */
 class IncidentHistoryRenderer implements ItemRenderer
@@ -26,7 +28,7 @@ class IncidentHistoryRenderer implements ItemRenderer
     public function assembleAttributes($item, Attributes $attributes, string $layout): void
     {
         $classes = ['incident-history'];
-        if ($item->type === 'notified') {
+        if ($item->type === IncidentHistoryType::NOTIFIED) {
             $classes[] = 'notification-state';
             if ($item->notification_state === 'suppressed') {
                 $classes[] = 'suppressed';
@@ -40,20 +42,16 @@ public function assembleAttributes($item, Attributes $attributes, string $layout
 
     public function assembleVisual($item, HtmlDocument $visual, string $layout): void
     {
-        if ($item->type === 'incident_severity_changed') {
+        if ($item->type === IncidentHistoryType::INCIDENT_SEVERITY_CHANGED) {
             $content = $item->new_severity->getIcon();
+        } elseif ($item->type === IncidentHistoryType::RECIPIENT_ROLE_CHANGED) {
+            $content = new IconBall($this->getRoleIcon($item));
         } else {
-            $content = new IconBall(match ($item->type) {
-                'opened'                    => Icons::OPENED,
-                'muted'                     => Icons::MUTE,
-                'unmuted'                   => Icons::UNMUTE,
-                'recipient_role_changed'    => $this->getRoleIcon($item),
-                'closed'                    => Icons::CLOSED,
-                'rule_matched'              => Icons::RULE_MATCHED,
-                'escalation_triggered'      => Icons::TRIGGERED,
-                'notified'                  => Icons::NOTIFIED,
-                default                     => Icons::UNDEFINED
-            });
+            try {
+                $content = Icons::forEnum($item->type);
+            } catch (UnhandledMatchError) {
+                $content = new IconBall(Icons::UNDEFINED);
+            }
         }
 
         $visual->addHtml($content);
@@ -119,18 +117,18 @@ protected function getRoleIcon(IncidentHistory $item): string
     protected function buildMessage(IncidentHistory $item): ValidHtml
     {
         switch ($item->type) {
-            case 'opened':
+            case IncidentHistoryType::OPENED:
                 $message = sprintf(
                     $this->translate('Incident opened at severity %s'),
                     $item->new_severity->getLabel()
                 );
 
                 break;
-            case 'closed':
+            case IncidentHistoryType::CLOSED:
                 $message = $this->translate('Incident closed');
 
                 break;
-            case "notified":
+            case IncidentHistoryType::NOTIFIED:
                 if (isset($item->contactgroup->name) && isset($item->contact->full_name)) {
                     if (isset($item->channel->type)) {
                         $message = sprintf(
@@ -200,15 +198,15 @@ protected function buildMessage(IncidentHistory $item): ValidHtml
                 }
 
                 break;
-            case 'incident_severity_changed':
+            case IncidentHistoryType::INCIDENT_SEVERITY_CHANGED:
                 $message = sprintf(
                     $this->translate('Incident severity changed from %s to %s'),
                     $item->old_severity->getLabel(),
                     $item->new_severity->getLabel()
                 );
 
                 break;
-            case 'recipient_role_changed':
+            case IncidentHistoryType::RECIPIENT_ROLE_CHANGED:
                 $newRole = $item->new_recipient_role;
                 $message = '';
                 if ($newRole === 'manager' || (! $newRole && $item->old_recipient_role === 'manager')) {
@@ -251,16 +249,17 @@ protected function buildMessage(IncidentHistory $item): ValidHtml
                 }
 
                 break;
-            case 'rule_matched':
+            case IncidentHistoryType::RULE_MATCHED:
                 if (isset($item->rule->name)) {
                     $message = sprintf($this->translate('Rule %s matched on this incident'), $item->rule->name);
                 } else {
                     $message = $this->translate('Unknown rule matched on this incident');
                 }
 
                 break;
-            case 'escalation_triggered':
+            case IncidentHistoryType::ESCALATION_TRIGGERED:
                 if (isset($item->rule->name)) {
+                    // TODO: No name is no reason to claim an unknown escalation, describe conditions instead
                     if (isset($item->rule_escalation->name)) {
                         $message = sprintf(
                             $this->translate('Rule %s reached escalation %s'),
@@ -278,11 +277,11 @@ protected function buildMessage(IncidentHistory $item): ValidHtml
                 }
 
                 break;
-            case 'muted':
+            case IncidentHistoryType::MUTED:
                 $message = $this->translate('Notifications for this incident have been muted');
 
                 break;
-            case 'unmuted':
+            case IncidentHistoryType::UNMUTED:
                 $message = $this->translate('Notifications for this incident have been unmuted');
 
                 break;

test/php/library/Notifications/Common/IncidentHistoryTypeTest.php

@@ -0,0 +1,90 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 Icinga GmbH <https://icinga.com>
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+namespace Tests\Icinga\Module\Notifications\Common;
+
+use Icinga\Module\Notifications\Common\IncidentHistoryType;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+
+class IncidentHistoryTypeTest extends TestCase
+{
+    public static function backingValueProvider(): array
+    {
+        return [
+            'incident_severity_changed' => [
+                IncidentHistoryType::INCIDENT_SEVERITY_CHANGED,
+                'incident_severity_changed'
+            ],
+            'escalation_triggered' => [IncidentHistoryType::ESCALATION_TRIGGERED, 'escalation_triggered'],
+            'opened' => [IncidentHistoryType::OPENED, 'opened'],
+            'closed' => [IncidentHistoryType::CLOSED, 'closed'],
+            'muted' => [IncidentHistoryType::MUTED, 'muted'],
+            'unmuted' => [IncidentHistoryType::UNMUTED, 'unmuted'],
+            'recipient_role_changed' => [
+                IncidentHistoryType::RECIPIENT_ROLE_CHANGED,
+                'recipient_role_changed'
+            ],
+            'notified' => [IncidentHistoryType::NOTIFIED, 'notified'],
+            'rule_matched' => [IncidentHistoryType::RULE_MATCHED, 'rule_matched']
+        ];
+    }
+
+    #[DataProvider('backingValueProvider')]
+    public function testBackingValueIsTheDbString(IncidentHistoryType $type, string $expected): void
+    {
+        $this->assertSame($expected, $type->value);
+    }
+
+    #[DataProvider('backingValueProvider')]
+    public function testFromParsesDbString(IncidentHistoryType $expected, string $dbValue): void
+    {
+        $this->assertSame($expected, IncidentHistoryType::from($dbValue));
+    }
+
+    #[DataProvider('backingValueProvider')]
+    public function testGetValueReturnsBackingValue(IncidentHistoryType $type, string $expected): void
+    {
+        $this->assertSame($expected, $type->getValue());
+    }
+
+    public function testGetLabelCoversAllCases(): void
+    {
+        $this->assertSame(
+            'Incident severity changed',
+            IncidentHistoryType::INCIDENT_SEVERITY_CHANGED->getLabel()
+        );
+        $this->assertSame('Escalation triggered', IncidentHistoryType::ESCALATION_TRIGGERED->getLabel());
+        $this->assertSame('Incident opened', IncidentHistoryType::OPENED->getLabel());
+        $this->assertSame('Incident closed', IncidentHistoryType::CLOSED->getLabel());
+        $this->assertSame('Incident muted', IncidentHistoryType::MUTED->getLabel());
+        $this->assertSame('Incident unmuted', IncidentHistoryType::UNMUTED->getLabel());
+        $this->assertSame(
+            'Recipient role changed',
+            IncidentHistoryType::RECIPIENT_ROLE_CHANGED->getLabel()
+        );
+        $this->assertSame('Notified', IncidentHistoryType::NOTIFIED->getLabel());
+        $this->assertSame('Rule matched', IncidentHistoryType::RULE_MATCHED->getLabel());
+    }
+
+    public function testAllCasesAreCovered(): void
+    {
+        $this->assertSame(
+            [
+                IncidentHistoryType::INCIDENT_SEVERITY_CHANGED,
+                IncidentHistoryType::ESCALATION_TRIGGERED,
+                IncidentHistoryType::CLOSED,
+                IncidentHistoryType::OPENED,
+                IncidentHistoryType::MUTED,
+                IncidentHistoryType::UNMUTED,
+                IncidentHistoryType::RECIPIENT_ROLE_CHANGED,
+                IncidentHistoryType::NOTIFIED,
+                IncidentHistoryType::RULE_MATCHED
+            ],
+            IncidentHistoryType::cases(),
+            'An IncidentHistoryType case was added or removed — update the test providers and this assertion'
+        );
+    }
+}