dohertj2/scadalink-design
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat(alarms): HiLo trigger type with per-band level, hysteresis, messages, overrides

Browse Source 
Adds a new HiLo alarm trigger type with four configurable setpoints
(LoLo / Lo / Hi / HiHi). Each setpoint carries an optional priority,
deadband (for hysteresis), and operator message. The site runtime emits
AlarmStateChanged with an AlarmLevel field so consumers can differentiate
warning vs critical bands.

Plumbing:
  - new AlarmLevel enum + AlarmStateChanged.Level/Message init properties
  - AlarmTriggerEditor (Blazor) gets a HiLo render with severity tinting
  - AlarmTriggerConfigCodec extracted from the editor for testability
  - sitestream.proto carries level + message over gRPC
  - SemanticValidator enforces numeric attribute, setpoint ordering,
    non-negative deadband
  - on-trigger scripts get an Alarm global (Name/Level/Priority/Message)
    so notification routing can branch by severity
  - per-instance InstanceAlarmOverride entity + EF migration + flattening
    step + CLI commands; HiLo overrides merge setpoint-by-setpoint, binary
    types whole-replace
  - DebugView shows a Level badge + per-band message tooltip
  - App.razor auto-reloads on permanent Blazor circuit failure
  - docker/regen-proto.sh automates the proto regen workflow (the linux/arm64
    protoc segfault means generated files are checked in for now)
This commit is contained in:
Joseph Doherty
2026-05-13 03:23:32 -04:00
parent 783da8e21a
commit 751248feb6
46 changed files with 4693 additions and 204 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
src/ScadaLink.TemplateEngine/Flattening/FlatteningService.cs
View File

@@ -1,3 +1,4 @@
using System.Text.Json;
using ScadaLink.Commons.Entities.Instances;
using ScadaLink.Commons.Entities.Sites;
using ScadaLink.Commons.Entities.Templates;
@@ -80,6 +81,7 @@ public class FlatteningService
// Step 5: Resolve alarms from inheritance chain
var alarms = ResolveInheritedAlarms(templateChain);
ResolveComposedAlarms(templateChain, compositionMap, composedTemplateChains, alarms);
ApplyInstanceAlarmOverrides(instance.AlarmOverrides, alarms);
// Step 6: Resolve scripts from inheritance chain
var scripts = ResolveInheritedScripts(templateChain);
@@ -292,6 +294,43 @@ public class FlatteningService
}
}
/// <summary>
/// Applies per-instance alarm overrides on top of the
/// inheritance-and-composition resolved alarms. Skips overrides for
/// alarms that are locked at the template level. For HiLo triggers the
/// override JSON is merged setpoint-by-setpoint (preserving inherited
/// keys not present in the override); for other trigger types the
/// override replaces the whole TriggerConfiguration.
/// </summary>
private static void ApplyInstanceAlarmOverrides(
ICollection<InstanceAlarmOverride> overrides,
Dictionary<string, ResolvedAlarm> alarms)
{
foreach (var ovr in overrides)
{
if (!alarms.TryGetValue(ovr.AlarmCanonicalName, out var existing))
continue; // Cannot add new alarms via overrides
if (existing.IsLocked)
continue; // Locked alarms cannot be overridden
var newConfig = existing.TriggerConfiguration;
if (!string.IsNullOrWhiteSpace(ovr.TriggerConfigurationOverride))
{
newConfig = existing.TriggerType == nameof(AlarmTriggerType.HiLo)
? MergeHiLoConfig(existing.TriggerConfiguration, ovr.TriggerConfigurationOverride)
: ovr.TriggerConfigurationOverride;
}
alarms[ovr.AlarmCanonicalName] = existing with
{
TriggerConfiguration = newConfig,
PriorityLevel = ovr.PriorityLevelOverride ?? existing.PriorityLevel,
Source = "Override"
};
}
}
private static void ApplyConnectionBindings(
ICollection<InstanceConnectionBinding> bindings,
Dictionary<string, ResolvedAttribute> attributes,
@@ -332,6 +371,18 @@ public class FlatteningService
if (result.TryGetValue(alarm.Name, out var existing) && existing.IsLocked)
continue;
// HiLo per-setpoint override: derived templates can supply a
// partial TriggerConfiguration (e.g., just `hi`) and have the
// remaining setpoints inherited. Other trigger types replace
// the whole config on override (current behavior).
var triggerConfig = alarm.TriggerConfiguration;
if (existing != null
&& alarm.TriggerType == AlarmTriggerType.HiLo
&& existing.TriggerType == nameof(AlarmTriggerType.HiLo))
{
triggerConfig = MergeHiLoConfig(existing.TriggerConfiguration, triggerConfig);
}
result[alarm.Name] = new ResolvedAlarm
{
CanonicalName = alarm.Name,
@@ -339,7 +390,7 @@ public class FlatteningService
PriorityLevel = alarm.PriorityLevel,
IsLocked = alarm.IsLocked,
TriggerType = alarm.TriggerType.ToString(),
TriggerConfiguration = alarm.TriggerConfiguration,
TriggerConfiguration = triggerConfig,
OnTriggerScriptCanonicalName = null, // Resolved later
Source = source
};
@@ -349,6 +400,61 @@ public class FlatteningService
return result;
}
/// <summary>
/// Merges a derived HiLo trigger configuration onto an inherited one.
/// Top-level keys present in <paramref name="derivedJson"/> override the
/// inherited values; keys absent in the derived config are inherited.
/// Returns the derived config verbatim on parse failure of either input —
/// the existing whole-replace behavior is the safe fallback.
/// </summary>
internal static string? MergeHiLoConfig(string? inheritedJson, string? derivedJson)
{
if (string.IsNullOrWhiteSpace(inheritedJson)) return derivedJson;
if (string.IsNullOrWhiteSpace(derivedJson)) return inheritedJson;
try
{
using var inheritedDoc = JsonDocument.Parse(inheritedJson);
using var derivedDoc = JsonDocument.Parse(derivedJson);
if (inheritedDoc.RootElement.ValueKind != JsonValueKind.Object
|| derivedDoc.RootElement.ValueKind != JsonValueKind.Object)
{
return derivedJson;
}
using var stream = new MemoryStream();
using (var writer = new Utf8JsonWriter(stream))
{
writer.WriteStartObject();
var derivedKeys = new HashSet<string>(StringComparer.Ordinal);
foreach (var prop in derivedDoc.RootElement.EnumerateObject())
derivedKeys.Add(prop.Name);
// Inherited keys not present in derived survive.
foreach (var prop in inheritedDoc.RootElement.EnumerateObject())
{
if (derivedKeys.Contains(prop.Name)) continue;
prop.WriteTo(writer);
}
// Derived keys win.
foreach (var prop in derivedDoc.RootElement.EnumerateObject())
{
prop.WriteTo(writer);
}
writer.WriteEndObject();
}
return System.Text.Encoding.UTF8.GetString(stream.ToArray());
}
catch (JsonException)
{
return derivedJson;
}
}
private static void ResolveComposedAlarms(
IReadOnlyList<Template> templateChain,
IReadOnlyDictionary<int, IReadOnlyList<TemplateComposition>> compositionMap,

88
src/ScadaLink.TemplateEngine/Services/InstanceService.cs
View File

@@ -169,6 +169,94 @@ public class InstanceService
}
}
/// <summary>
/// Sets a per-instance alarm override. The alarm must exist on the
/// template and must not be locked. For HiLo alarms, the override JSON
/// merges into the inherited TriggerConfiguration setpoint-by-setpoint;
/// for binary trigger types, it replaces the whole config.
/// </summary>
public async Task<Result<InstanceAlarmOverride>> SetAlarmOverrideAsync(
int instanceId,
string alarmCanonicalName,
string? triggerConfigurationOverride,
int? priorityLevelOverride,
string user,
CancellationToken cancellationToken = default)
{
var instance = await _repository.GetInstanceByIdAsync(instanceId, cancellationToken);
if (instance == null)
return Result<InstanceAlarmOverride>.Failure($"Instance with ID {instanceId} not found.");
// Verify alarm exists in the template and is not locked. Only direct
// template alarms are checked here — composed-member overrides go
// through but are silently ignored at runtime if the name doesn't
// match (same behavior as attribute overrides).
var templateAlarms = await _repository.GetAlarmsByTemplateIdAsync(instance.TemplateId, cancellationToken);
var templateAlarm = templateAlarms.FirstOrDefault(a => a.Name == alarmCanonicalName);
if (templateAlarm != null && templateAlarm.IsLocked)
{
return Result<InstanceAlarmOverride>.Failure(
$"Alarm '{alarmCanonicalName}' is locked and cannot be overridden.");
}
var existingOverride = await _repository.GetAlarmOverrideAsync(
instanceId, alarmCanonicalName, cancellationToken);
if (existingOverride != null)
{
existingOverride.TriggerConfigurationOverride = triggerConfigurationOverride;
existingOverride.PriorityLevelOverride = priorityLevelOverride;
await _repository.UpdateInstanceAlarmOverrideAsync(existingOverride, cancellationToken);
await _repository.SaveChangesAsync(cancellationToken);
await _auditService.LogAsync(user, "UpdateAlarmOverride", "InstanceAlarmOverride",
existingOverride.Id.ToString(), alarmCanonicalName, existingOverride, cancellationToken);
return Result<InstanceAlarmOverride>.Success(existingOverride);
}
else
{
var newOverride = new InstanceAlarmOverride(alarmCanonicalName)
{
InstanceId = instanceId,
TriggerConfigurationOverride = triggerConfigurationOverride,
PriorityLevelOverride = priorityLevelOverride
};
await _repository.AddInstanceAlarmOverrideAsync(newOverride, cancellationToken);
await _repository.SaveChangesAsync(cancellationToken);
await _auditService.LogAsync(user, "CreateAlarmOverride", "InstanceAlarmOverride",
newOverride.Id.ToString(), alarmCanonicalName, newOverride, cancellationToken);
return Result<InstanceAlarmOverride>.Success(newOverride);
}
}
/// <summary>
/// Removes a per-instance alarm override. After removal the instance
/// inherits the template alarm config unchanged.
/// </summary>
public async Task<Result<bool>> DeleteAlarmOverrideAsync(
int instanceId,
string alarmCanonicalName,
string user,
CancellationToken cancellationToken = default)
{
var existing = await _repository.GetAlarmOverrideAsync(
instanceId, alarmCanonicalName, cancellationToken);
if (existing == null)
return Result<bool>.Failure($"No alarm override for '{alarmCanonicalName}' on instance {instanceId}.");
await _repository.DeleteInstanceAlarmOverrideAsync(existing.Id, cancellationToken);
await _repository.SaveChangesAsync(cancellationToken);
await _auditService.LogAsync(user, "DeleteAlarmOverride", "InstanceAlarmOverride",
existing.Id.ToString(), alarmCanonicalName, existing, cancellationToken);
return Result<bool>.Success(true);
}
/// <summary>
/// Sets connection bindings for an instance in bulk.
/// </summary>

69
src/ScadaLink.TemplateEngine/Validation/SemanticValidator.cs
View File

@@ -136,6 +136,75 @@ public class SemanticValidator
}
}
// HiLo requires numeric attribute + ordered setpoints
if (alarm.TriggerType == "HiLo" && !string.IsNullOrWhiteSpace(alarm.TriggerConfiguration))
{
var attrName = ValidationService.ExtractAttributeNameFromTriggerConfig(alarm.TriggerConfiguration);
if (attrName != null && attributeMap.TryGetValue(attrName, out var attr))
{
if (!NumericDataTypes.Contains(attr.DataType))
{
errors.Add(ValidationEntry.Error(ValidationCategory.TriggerOperandType,
$"Alarm '{alarm.CanonicalName}' uses HiLo trigger on attribute '{attrName}' which has non-numeric type '{attr.DataType}'.",
alarm.CanonicalName));
}
}
var setpoints = ValidationService.ExtractHiLoSetpoints(alarm.TriggerConfiguration);
// At least one setpoint must be configured — otherwise the alarm
// can never fire.
if (!setpoints.LoLo.HasValue && !setpoints.Lo.HasValue
&& !setpoints.Hi.HasValue && !setpoints.HiHi.HasValue)
{
warnings.Add(ValidationEntry.Warning(ValidationCategory.TriggerOperandType,
$"Alarm '{alarm.CanonicalName}' is HiLo but no setpoints (LoLo/Lo/Hi/HiHi) are configured — it will never fire.",
alarm.CanonicalName));
}
// Ordering: LoLo ≤ Lo, Hi ≤ HiHi, and the highest Lo-side band
// must sit strictly below the lowest Hi-side band — otherwise the
// bands overlap and the evaluator's behavior is ambiguous.
if (setpoints.LoLo is { } loLo && setpoints.Lo is { } lo && loLo > lo)
{
errors.Add(ValidationEntry.Error(ValidationCategory.TriggerOperandType,
$"Alarm '{alarm.CanonicalName}' HiLo setpoints out of order: LoLo ({loLo}) must be ≤ Lo ({lo}).",
alarm.CanonicalName));
}
if (setpoints.Hi is { } hi && setpoints.HiHi is { } hiHi && hi > hiHi)
{
errors.Add(ValidationEntry.Error(ValidationCategory.TriggerOperandType,
$"Alarm '{alarm.CanonicalName}' HiLo setpoints out of order: Hi ({hi}) must be ≤ HiHi ({hiHi}).",
alarm.CanonicalName));
}
var highestLowSide = setpoints.Lo ?? setpoints.LoLo;
var lowestHighSide = setpoints.Hi ?? setpoints.HiHi;
if (highestLowSide is { } lowSide && lowestHighSide is { } highSide
&& lowSide >= highSide)
{
errors.Add(ValidationEntry.Error(ValidationCategory.TriggerOperandType,
$"Alarm '{alarm.CanonicalName}' HiLo bands overlap: low-side setpoint ({lowSide}) must be strictly less than high-side setpoint ({highSide}).",
alarm.CanonicalName));
}
// Deadbands must be non-negative — negative deadband would invert
// the hysteresis (alarm could escape faster than it entered).
foreach (var (name, value) in new (string, double?)[] {
("LoLo deadband", setpoints.LoLoDeadband),
("Lo deadband", setpoints.LoDeadband),
("Hi deadband", setpoints.HiDeadband),
("HiHi deadband", setpoints.HiHiDeadband)
})
{
if (value is { } d && d < 0)
{
errors.Add(ValidationEntry.Error(ValidationCategory.TriggerOperandType,
$"Alarm '{alarm.CanonicalName}' {name} ({d}) must be non-negative.",
alarm.CanonicalName));
}
}
}
// On-trigger script must exist
if (!string.IsNullOrWhiteSpace(alarm.OnTriggerScriptCanonicalName) &&
!scriptNames.Contains(alarm.OnTriggerScriptCanonicalName))

46
src/ScadaLink.TemplateEngine/Validation/ValidationService.cs
View File

@@ -232,4 +232,50 @@ public class ValidationService
}
return null;
}
/// <summary>
/// Extracts the four HiLo setpoints from a trigger configuration JSON.
/// Any unset (or non-numeric) setpoint comes back as <c>null</c>. Returns
/// all-nulls on malformed JSON — callers should treat that as "nothing to
/// validate" and let other checks surface the deeper problem.
/// </summary>
internal static HiLoSetpoints ExtractHiLoSetpoints(string triggerConfigJson)
{
try
{
using var doc = JsonDocument.Parse(triggerConfigJson);
var root = doc.RootElement;
return new HiLoSetpoints(
LoLo: ReadDouble(root, "loLo"),
Lo: ReadDouble(root, "lo"),
Hi: ReadDouble(root, "hi"),
HiHi: ReadDouble(root, "hiHi"),
LoLoDeadband: ReadDouble(root, "loLoDeadband"),
LoDeadband: ReadDouble(root, "loDeadband"),
HiDeadband: ReadDouble(root, "hiDeadband"),
HiHiDeadband: ReadDouble(root, "hiHiDeadband"));
}
catch (JsonException)
{
return new HiLoSetpoints(null, null, null, null, null, null, null, null);
}
}
private static double? ReadDouble(JsonElement el, string name)
{
if (!el.TryGetProperty(name, out var p)) return null;
return p.ValueKind switch
{
JsonValueKind.Number => p.GetDouble(),
JsonValueKind.String when double.TryParse(p.GetString(),
System.Globalization.NumberStyles.Float,
System.Globalization.CultureInfo.InvariantCulture, out var v) => v,
_ => null
};
}
}
internal readonly record struct HiLoSetpoints(
double? LoLo, double? Lo, double? Hi, double? HiHi,
double? LoLoDeadband = null, double? LoDeadband = null,
double? HiDeadband = null, double? HiHiDeadband = null);