fix(alarms): Severity runs one direction, higher = more urgent; raw priority kept (#129)

AlarmConditionState.Severity mixed two conventions: OPC UA rows carried Part 9
Severity (higher = more severe) while MxGateway native alarms and computed
alarms carried a raw AVEVA-style priority (1 = most urgent). Every consumer
ranks higher as worse, so Worst Severity, the severity filter/sort and the
site event-log Error threshold picked the LEAST urgent MxGateway/computed
alarms.

- AlarmPriorityBands: the OtOpcUa GalaxyAlarmPriority table (lmxopcua#887,
  b61f3e05), value for value: 1-250 -> 1000, 251-500 -> 750, 501-750 -> 500,
  751-999 -> 250; <= 0 clamps to Critical, > 999 to Low.
- MxGatewayAlarmMapper bands the gateway severity (= AVEVA priority);
  AlarmConditionStateFactory.ForComputed bands PriorityLevel. OPC UA unchanged.
- AlarmConditionState gains trailing Priority (int?): the raw source number,
  exactly the pre-#129 Severity. AlarmStateChanged.Priority and the wire
  AlarmStateUpdate.priority keep that meaning (no proto change); central derives
  Severity by kind (SeverityFromPriority), so an older site decodes correctly.
- ScriptAlarm gains trailing Priority. The native MES 900-999 band and the MES
  API Severity/MinSeverity/MaxSeverity key off Priority; rig seed scripts moved
  from a.Severity to a.Priority, so MES output is unchanged.
- AlarmActor raise logs Error when the banded severity >= 700 (same threshold
  as NativeAlarmActor): priority 1-500 Error, 501+ Warning (was raw >= 700).
- NativeAlarmActor upgrades pre-#129 native_alarm_state rows on rehydrate.
- Debug snapshot decode restores Condition.Priority from the row's priority.
- Docs: Commons, DCL, SiteRuntime, Communication, CentralUI, InboundAPI,
  HighLevelReqs, MES alarm-status plan, CLAUDE.md.

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
This commit is contained in:
Joseph Doherty
2026-11-12 13:58:28 -05:00
parent e36cd6055e
commit dd4f1c2aa3
39 changed files with 686 additions and 120 deletions
@@ -26,7 +26,7 @@ public class TemplateNativeAlarmSource
/// <summary>
/// When true, every condition mirrored under this binding is MES-reportable
/// (<c>AlarmStateChanged.IsMesReportable</c> / <c>ScriptAlarm.IsMesReportable</c>). Additive to the
/// 900-999 severity-band convention, which still flags a condition on its own. Default false.
/// 900-999 priority-band convention (on <c>ScriptAlarm.Priority</c>, Gitea #129), which still flags a condition on its own. Default false.
/// Overridable per instance via <c>InstanceNativeAlarmSourceOverride.IsMesReportableOverride</c>.
/// </summary>
public bool IsMesReportable { get; set; }
@@ -3,6 +3,17 @@ using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums;
namespace ZB.MOM.WW.ScadaBridge.Commons.Messages.Streaming;
/// <summary>An alarm's state change, as streamed site → central and kept in the Debug View snapshot.</summary>
/// <param name="InstanceUniqueName">The instance the alarm belongs to.</param>
/// <param name="AlarmName">The alarm's name (a native condition's source reference).</param>
/// <param name="State">Active or Normal.</param>
/// <param name="Priority">
/// The source's raw number (Gitea #129): the computed alarm's <c>PriorityLevel</c>, the AVEVA priority of an
/// MxAccess condition, the Part 9 Severity of an OPC UA condition — i.e. <c>Condition.Priority</c>. This is what
/// the stream's <c>AlarmStateUpdate.priority</c> carries (meaning unchanged since before #129). For ranking use
/// <see cref="Condition"/>.<see cref="AlarmConditionState.Severity"/>, which is higher = more urgent for every kind.
/// </param>
/// <param name="Timestamp">When the transition happened.</param>
public record AlarmStateChanged(
string InstanceUniqueName,
string AlarmName,
@@ -119,7 +130,7 @@ public record AlarmStateChanged(
/// snapshot and on every event it relays to the site stream. For a native condition it is
/// the binding-level flag (<c>ResolvedNativeAlarmSource.IsMesReportable</c>, Gitea #59), set by
/// the owning <c>NativeAlarmActor</c> — there is still no per-condition config row; the
/// 900-999 severity band remains an independent, additive signal. Carried to central on
/// 900-999 priority band (on <see cref="Priority"/>, Gitea #129) remains an independent, additive signal. Carried to central on
/// <c>AlarmStateUpdate</c> field 25 and <c>DebugAlarmStateDto</c> field 20 (Gitea #60);
/// a pre-#60 site sends the proto3 default. Additive; default false.
/// </summary>
@@ -8,17 +8,35 @@ namespace ZB.MOM.WW.ScadaBridge.Commons.Types.Alarms;
/// onto them, so they are modeled as independent flags plus a 0–1000 severity.
/// Computed alarms populate this from State + Priority; native alarms mirror it
/// from the source.
///
/// <para>
/// <b>One direction (Gitea #129):</b> <see cref="Severity"/> is always OPC UA Part 9 direction,
/// <b>higher = more urgent</b>, whatever the source. OPC UA rows carry the server's Part 9 Severity;
/// MxAccess Gateway rows and computed alarms carry their AVEVA-style priority (1 = most urgent)
/// mapped through <see cref="AlarmPriorityBands"/> (1–250 → 1000, 251–500 → 750, 501–750 → 500,
/// 751–999 → 250). Sort, filter and threshold on <see cref="Severity"/>, never on <see cref="Priority"/>.
/// </para>
/// </summary>
/// <param name="Active">Active vs Inactive.</param>
/// <param name="Acknowledged">Acked vs Unacked.</param>
/// <param name="Confirmed">Confirmed vs Unconfirmed; null when the condition is not confirmable.</param>
/// <param name="Shelve">Shelving sub-state.</param>
/// <param name="Suppressed">Whether the source has suppressed the condition.</param>
/// <param name="Severity">Severity on the unified 0–1000 scale.</param>
/// <param name="Severity">Severity on the unified 0–1000 scale, higher = more urgent for every source.</param>
/// <param name="Priority">
/// The source's own number, verbatim — exactly what <see cref="Severity"/> carried before Gitea #129:
/// the AVEVA alarm priority for MxAccess Gateway rows (clamped 0–1000; 1 = most urgent), the configured
/// <c>PriorityLevel</c> for computed alarms, and the Part 9 Severity again for OPC UA rows (OPC UA has
/// no separate priority). Kept so no information is lost and so the native MES 900–999 band selects the
/// same alarms it always did. Its direction depends on the source, so do not sort or threshold on it.
/// <c>null</c> only on a condition persisted before #129 or built without one; readers fall back to
/// <see cref="Severity"/>.
/// </param>
public record AlarmConditionState(
bool Active,
bool Acknowledged,
bool? Confirmed,
AlarmShelveState Shelve,
bool Suppressed,
int Severity);
int Severity,
int? Priority = null);
@@ -7,13 +7,32 @@ public static class AlarmConditionStateFactory
{
/// <summary>
/// Computed alarms have no native ack/shelve/suppress lifecycle: they are
/// auto-acked, never shelved or suppressed, not confirmable, and their
/// severity is the configured priority. Active mirrors the alarm State.
/// auto-acked, never shelved or suppressed, not confirmable. Their configured
/// priority (lower = more urgent) is banded onto Severity through
/// <see cref="AlarmPriorityBands"/> and kept verbatim on
/// <see cref="AlarmConditionState.Priority"/> (Gitea #129). Active mirrors the alarm State.
/// </summary>
/// <param name="state">The current alarm state used to derive the Active flag.</param>
/// <param name="priority">Configured priority mapped to the Severity field (0–1000).</param>
/// <param name="priority">Configured priority (0–1000, lower = more urgent).</param>
/// <returns>An <see cref="AlarmConditionState"/> reflecting the computed alarm's lifecycle (auto-acked, unshelved, not suppressed).</returns>
public static AlarmConditionState ForComputed(AlarmState state, int priority) =>
new(Active: state == AlarmState.Active, Acknowledged: true, Confirmed: null,
Shelve: AlarmShelveState.Unshelved, Suppressed: false, Severity: priority);
Shelve: AlarmShelveState.Unshelved, Suppressed: false,
Severity: AlarmPriorityBands.ToSeverity(priority), Priority: priority);
/// <summary>
/// Derives the unified Severity from the raw priority an <c>AlarmStateChanged</c> carries on the
/// site stream (<c>AlarmStateUpdate.priority</c>), which is all central receives (Gitea #129).
/// OPC UA rows carry their Part 9 Severity there already; MxAccess Gateway and computed rows carry
/// an AVEVA-style priority that is banded. Because the wire field kept its pre-#129 meaning, this
/// is also correct for a site still running an older build.
/// </summary>
/// <param name="kind">The alarm's kind.</param>
/// <param name="priority">The raw priority from the wire.</param>
/// <returns>The severity on the 0–1000 scale, higher = more urgent.</returns>
public static int SeverityFromPriority(AlarmKind kind, int priority) => kind switch
{
AlarmKind.NativeOpcUa => Math.Clamp(priority, 0, 1000),
_ => AlarmPriorityBands.ToSeverity(priority),
};
}
@@ -0,0 +1,72 @@
namespace ZB.MOM.WW.ScadaBridge.Commons.Types.Alarms;
/// <summary>
/// Maps an alarm <b>priority</b> (AVEVA convention: 1 = most urgent … 999 = least) onto the unified
/// <see cref="AlarmConditionState.Severity"/> scale (OPC UA Part 9 direction: higher = more urgent).
/// Used for MxAccess Gateway native alarms and for computed alarms' <c>PriorityLevel</c> (Gitea #129).
/// </summary>
/// <remarks>
/// <para>
/// This is the same table OtOpcUa's <c>GalaxyAlarmPriority.Map</c> uses since lmxopcua#887 (commit
/// <c>b61f3e05</c>), value for value, so a Galaxy alarm reads the same Severity whether ScadaBridge
/// gets it through OtOpcUa (OPC UA adapter) or straight from mxaccessgw (MxGateway adapter). AVEVA's
/// default priority ranges, most urgent first:
/// </para>
/// <list type="table">
/// <listheader><term>Priority</term><description>AVEVA severity → Severity</description></listheader>
/// <item><term>1–250</term><description>1 Critical → 1000</description></item>
/// <item><term>251–500</term><description>2 High → 750</description></item>
/// <item><term>501–750</term><description>3 Medium → 500</description></item>
/// <item><term>751–999</term><description>4 Low → 250</description></item>
/// </list>
/// <para>
/// A priority outside 1–999 is clamped into it first, exactly as OtOpcUa does: 0, negatives and
/// <see cref="int.MinValue"/> read Critical (1000); anything above 999 reads Low (250). The mapping is
/// monotonic: a lower (more urgent) priority never yields a lower Severity.
/// </para>
/// <para>
/// OtOpcUa's table also has a history-only "not an alarm" row (AVEVA <i>severity</i> 0 → Severity 1, for
/// System.*/User.* events in A&amp;E history). It has no counterpart here: the MxGateway live feed carries
/// alarms only, and only their priority, and a computed alarm is always an alarm.
/// </para>
/// <para>
/// The raw priority is never thrown away: it stays on <see cref="AlarmConditionState.Priority"/> and
/// <c>AlarmStateChanged.Priority</c>, which is what the native MES 900–999 band keys off.
/// Change the table here only, and keep it in step with OtOpcUa's.
/// </para>
/// </remarks>
public static class AlarmPriorityBands
{
/// <summary>The last priority of AVEVA's default Critical range (1–250).</summary>
public const int CriticalMaxPriority = 250;
/// <summary>The last priority of AVEVA's default High range (251–500).</summary>
public const int HighMaxPriority = 500;
/// <summary>The last priority of AVEVA's default Medium range (501–750); 751–999 is Low.</summary>
public const int MediumMaxPriority = 750;
/// <summary>Severity of the Low band (priority 751–999).</summary>
public const int SeverityLow = 250;
/// <summary>Severity of the Medium band (priority 501–750).</summary>
public const int SeverityMedium = 500;
/// <summary>Severity of the High band (priority 251–500).</summary>
public const int SeverityHigh = 750;
/// <summary>Severity of the Critical band (priority 1–250).</summary>
public const int SeverityCritical = 1000;
/// <summary>Maps an AVEVA-style priority onto the unified severity.</summary>
/// <param name="priority">The priority (1 = most urgent … 999 = least; clamped into 1–999).</param>
/// <returns>The severity on the 0–1000 scale, 1000 = most urgent.</returns>
public static int ToSeverity(int priority) => priority switch
{
// The first arm also takes 0 and negatives, the last anything above 999: the clamp into 1–999.
<= CriticalMaxPriority => SeverityCritical,
<= HighMaxPriority => SeverityHigh,
<= MediumMaxPriority => SeverityMedium,
_ => SeverityLow,
};
}
@@ -161,7 +161,7 @@ public sealed record ResolvedNativeAlarmSource
public string Source { get; init; } = "Template";
/// <summary>
/// Gets whether every condition under this binding is MES-reportable (effective value after
/// the instance override). Additive to the 900-999 severity band.
/// the instance override). Additive to the 900-999 priority band (Gitea #129).
/// </summary>
public bool IsMesReportable { get; init; }
/// <summary>
@@ -35,7 +35,11 @@ namespace ZB.MOM.WW.ScadaBridge.Commons.Types.Scripts;
/// <param name="Confirmed">Confirmed vs unconfirmed; <c>null</c> when the condition is not confirmable.</param>
/// <param name="Shelved">Whether the source has shelved the condition (any shelve sub-state).</param>
/// <param name="Suppressed">Whether the source has suppressed the condition.</param>
/// <param name="Severity">Severity on the unified 0–1000 scale.</param>
/// <param name="Severity">
/// Severity on the unified 0–1000 scale, <b>higher = more urgent</b> for every kind (Gitea #129):
/// OPC UA Part 9 Severity verbatim; MxAccess and computed priorities banded 1–250 → 1000,
/// 251–500 → 750, 501–750 → 500, 751–999 → 250. Sort and threshold on this.
/// </param>
/// <param name="Kind">"Computed", "NativeOpcUa" or "NativeMxAccess".</param>
/// <param name="Message">Event/per-band operator message; may be empty.</param>
/// <param name="AlarmTypeName">Native alarm type (e.g. "AnalogLimitAlarm.HiHi"); empty for computed alarms.</param>
@@ -59,6 +63,13 @@ namespace ZB.MOM.WW.ScadaBridge.Commons.Types.Scripts;
/// True when the deployed configuration flags the alarm as MES-reportable (template
/// checkbox or instance override). For native conditions it is the source binding's flag (Gitea #59).
/// </param>
/// <param name="Priority">
/// The source's raw number, verbatim — what <paramref name="Severity"/> held before Gitea #129: the
/// AVEVA alarm priority for MxAccess (1 = most urgent), the configured <c>PriorityLevel</c> for computed
/// alarms, the Part 9 Severity for OPC UA (no separate priority). The native MES 900–999 band and the MES
/// API's <c>Severity</c>/<c>MinSeverity</c>/<c>MaxSeverity</c> (a 0–999 priority) key off this.
/// Its direction differs by kind; do not rank alarms by it.
/// </param>
public sealed record ScriptAlarm(
string Name,
string SourceReference,
@@ -81,4 +92,5 @@ public sealed record ScriptAlarm(
string CurrentValue,
string LimitValue,
bool IsConfiguredPlaceholder,
bool IsMesReportable = false);
bool IsMesReportable = false,
int Priority = 0);