fix(historian): read-only historian bindings + ProvisionTags policy; provision OPC UA type names (#899, #898)
v2-ci / unit-tests (push) Has been cancelled

#899 — EnsureTags is an upsert, so binding a node to an existing AVEVA tag via
historianTagname re-typed/re-described it on every add and host start.
- TagConfig `historianReadOnly: true` (TagConfigIntent -> RawTagPlan.HistorianReadOnly):
  HistoryRead from an existing historian tag that OtOpcUa never provisions and never
  records into (AddressSpaceApplier.IsOwnedHistorizedValue gates both the EnsureTags
  hook and the recorder feed). Node-inert: surgical, not mirrored on UNS refs, in the
  RawTagPlan equality/hash. A non-bool value is the deploy error HistorianReadOnlyInvalid.
  AdminUI: CSV column HistorianReadOnly (strict), TagHistorizeConfig reads via the
  runtime parse.
- ServerHistorian:ProvisionTags = CreateOrUpdate (default, unchanged) | CreateOnly
  (Gateway only: TagExistsAsync first, existing tags left alone, failed lookup not
  sent) | Off. Unknown value / CreateOnly on a SQL backend fail host start.
- Default for an explicit historianTagname stays OWNED: overrides pin owned history
  across renames, a read-only default would silently stop provisioning + recording.

#898 — the hook parsed Tag.DataType (an OPC UA name) as DriverDataType, so historized
Float/Double/Byte/SByte tags were never provisioned. New shared
HistorianDataTypeNames.TryResolve: Float->Float32, Double->Float64, Byte/SByte->Int16
(lossless, provisioned as Int2); unmapped names logged at Information. Gateway now skips
Int64/UInt64 (HistorianGateway cannot create Int8/UInt8: lossless-cast-or-reject).

UPGRADE: the first host start after this provisions (upserts) every existing historized
Float/Double/Byte/SByte tag. Mark foreign-tag bindings historianReadOnly, or set
ServerHistorian:ProvisionTags=CreateOnly/Off, before upgrading (docs/Historian.md).

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
This commit is contained in:
Joseph Doherty
2026-11-13 01:16:23 -05:00
parent eec87d3f74
commit 6c4d29902e
36 changed files with 1015 additions and 60 deletions
@@ -42,7 +42,7 @@ public static class RawTagCsvMapper
// Root TagConfig keys owned by the flag columns — stripped from the export residual so the
// TagConfigJson fallback never duplicates a value already carried by a dedicated column.
private static readonly string[] FlagKeys =
["isHistorized", "historianTagname", "isArray", "arrayLength", "alarm"];
["isHistorized", "historianTagname", "historianReadOnly", "isArray", "arrayLength", "alarm"];
// ---------------------------------------------------------------------------------------- Import
@@ -213,7 +213,8 @@ public static class RawTagCsvMapper
// Historize flags.
var isHistorized = ParseFlag("IsHistorized", Cell("IsHistorized"));
json = TagHistorizeConfig.Set(json, isHistorized, Cell("HistorianTagname"));
json = TagHistorizeConfig.Set(json, isHistorized, Cell("HistorianTagname"),
ParseFlag("HistorianReadOnly", Cell("HistorianReadOnly")));
// Array flags.
var isArray = ParseFlag("IsArray", Cell("IsArray"));
@@ -406,6 +407,7 @@ public static class RawTagCsvMapper
tag.PollGroupId ?? "",
hist.IsHistorized ? "true" : "",
hist.HistorianTagname,
hist.HistorianReadOnly ? "true" : "",
array.IsArray ? "true" : "",
array.ArrayLength?.ToString(CultureInfo.InvariantCulture) ?? "",
alarm.IsAlarm ? alarm.AlarmType : "",
@@ -433,6 +433,7 @@ public static class CsvColumnMap
"PollGroup",
"IsHistorized",
"HistorianTagname",
"HistorianReadOnly",
"IsArray",
"ArrayLength",
"Alarm.AlarmType",
@@ -1,10 +1,15 @@
using ZB.MOM.WW.OtOpcUa.Commons.Types;
namespace ZB.MOM.WW.OtOpcUa.AdminUI.Uns.TagEditors;
/// <summary>
/// Pure, driver-agnostic merge helper for the two server-side HistoryRead intent keys at the ROOT of a
/// tag's <c>TagConfig</c> JSON: <c>isHistorized</c> (camelCase bool — omit/false default) and
/// <c>historianTagname</c> (camelCase string override — omit when blank). These map to what the server's
/// <c>AddressSpaceComposer.ExtractTagHistorize</c> reads (see <c>docs/Historian.md</c>).
/// Pure, driver-agnostic merge helper for the server-side HistoryRead intent keys at the ROOT of a
/// tag's <c>TagConfig</c> JSON: <c>isHistorized</c> (camelCase bool — omit/false default),
/// <c>historianTagname</c> (camelCase string override — omit when blank) and <c>historianReadOnly</c>
/// (lmxopcua#899 — camelCase bool, omit/false default: the history is read from an existing historian tag
/// OtOpcUa never provisions or records into). These map to what the server's <see cref="TagConfigIntent"/>
/// reads (see <c>docs/Historian.md</c>); <see cref="Read"/> uses that same parse, so what the AdminUI shows is
/// what the runtime does.
///
/// <para>
/// This is the TagModal-merge seam: the TagModal owns the canonical TagConfig JSON; the driver's typed
@@ -17,10 +22,11 @@ namespace ZB.MOM.WW.OtOpcUa.AdminUI.Uns.TagEditors;
/// </summary>
public static class TagHistorizeConfig
{
/// <summary>The two history-intent values parsed from a TagConfig JSON's root.</summary>
/// <summary>The history-intent values parsed from a TagConfig JSON's root.</summary>
/// <param name="IsHistorized">Whether the server exposes OPC UA HistoryRead over this tag's node.</param>
/// <param name="HistorianTagname">Optional historian tagname override; <c>""</c> means default to the tag's FullName.</param>
public readonly record struct HistorizeState(bool IsHistorized, string HistorianTagname);
/// <param name="HistorianReadOnly">Whether the historian tag is a read-only binding OtOpcUa never provisions or records into.</param>
public readonly record struct HistorizeState(bool IsHistorized, string HistorianTagname, bool HistorianReadOnly = false);
/// <summary>Reads the history-intent keys from a TagConfig JSON, defaulting any absent key
/// (null/blank/malformed input ⇒ <c>(false, "")</c>).</summary>
@@ -31,7 +37,9 @@ public static class TagHistorizeConfig
var o = TagConfigJson.ParseOrNew(json);
return new HistorizeState(
TagConfigJson.GetBool(o, "isHistorized"),
TagConfigJson.GetString(o, "historianTagname") ?? "");
TagConfigJson.GetString(o, "historianTagname") ?? "",
// The runtime's own parse (only a JSON true counts), not a lenient re-read.
TagConfigIntent.Parse(json).HistorianReadOnly);
}
/// <summary>Merges the two history-intent keys into <paramref name="json"/>, preserving every other
@@ -41,13 +49,17 @@ public static class TagHistorizeConfig
/// <param name="json">The tag's existing TagConfig JSON, or null/empty to start from a new object.</param>
/// <param name="isHistorized">Whether the server should expose OPC UA HistoryRead over this tag's node.</param>
/// <param name="historianTagname">Optional historian tagname override; null/blank omits the key.</param>
/// <returns>The merged TagConfig JSON with the two history-intent keys applied.</returns>
public static string Set(string? json, bool isHistorized, string? historianTagname)
/// <param name="historianReadOnly"><see langword="true"/> writes <c>historianReadOnly: true</c>, <see langword="false"/>
/// drops the key (absent ⇒ owned), <see langword="null"/> leaves whatever the JSON already carries untouched.</param>
/// <returns>The merged TagConfig JSON with the history-intent keys applied.</returns>
public static string Set(string? json, bool isHistorized, string? historianTagname, bool? historianReadOnly = null)
{
var o = TagConfigJson.ParseOrNew(json);
TagConfigJson.Set(o, "isHistorized", isHistorized ? true : null);
TagConfigJson.Set(o, "historianTagname",
string.IsNullOrWhiteSpace(historianTagname) ? null : historianTagname.Trim());
if (historianReadOnly is { } readOnly)
TagConfigJson.Set(o, TagConfigIntent.HistorianReadOnlyKey, readOnly ? true : null);
return TagConfigJson.Serialize(o);
}
}