fix(historian): read-only historian bindings + ProvisionTags policy; provision OPC UA type names (#899, #898)
v2-ci / unit-tests (push) Has been cancelled
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:
@@ -18,13 +18,22 @@ namespace ZB.MOM.WW.OtOpcUa.Commons.Types;
|
||||
/// <param name="HistorianTagname">Non-whitespace <c>historianTagname</c> string override, else <see langword="null"/> (not trimmed).</param>
|
||||
/// <param name="IsArray"><c>isArray</c> bool.</param>
|
||||
/// <param name="ArrayLength"><c>arrayLength</c> honoured ONLY when <see cref="IsArray"/> and a JSON number fitting <see cref="uint"/>; else <see langword="null"/>.</param>
|
||||
/// <param name="HistorianReadOnly"><c>historianReadOnly</c> — true only when the value is a bool <c>true</c> (lmxopcua#899):
|
||||
/// the tag's history is READ from an existing historian tag that OtOpcUa does not own, so OtOpcUa never provisions
|
||||
/// (<c>EnsureTags</c>) it and never records captured values into it. Absent / <c>false</c> ⇒ an owned tag (the
|
||||
/// behaviour before #899). Any other JSON value is a deploy error (<c>DraftValidator</c>, see
|
||||
/// <see cref="HasMalformedHistorianReadOnly"/>), never silently "owned".</param>
|
||||
public sealed record TagConfigIntent(
|
||||
TagAlarmIntent? Alarm,
|
||||
bool IsHistorized,
|
||||
string? HistorianTagname,
|
||||
bool IsArray,
|
||||
uint? ArrayLength)
|
||||
uint? ArrayLength,
|
||||
bool HistorianReadOnly = false)
|
||||
{
|
||||
/// <summary>The <c>TagConfig</c> root key of the read-only historian binding (lmxopcua#899).</summary>
|
||||
public const string HistorianReadOnlyKey = "historianReadOnly";
|
||||
|
||||
/// <summary>
|
||||
/// Parse a Tag's schemaless <c>TagConfig</c> JSON into the cross-driver platform intents.
|
||||
/// Never throws: malformed JSON / non-object root / blank / null ⇒ all intents default.
|
||||
@@ -47,9 +56,11 @@ public sealed record TagConfigIntent(
|
||||
|
||||
var (isHistorized, historianTagname) = ParseHistorize(root);
|
||||
var (isArray, arrayLength) = ParseArray(root);
|
||||
var historianReadOnly = root.TryGetProperty(HistorianReadOnlyKey, out var roEl)
|
||||
&& roEl.ValueKind == JsonValueKind.True;
|
||||
|
||||
return new TagConfigIntent(
|
||||
ParseAlarm(root), isHistorized, historianTagname, isArray, arrayLength);
|
||||
ParseAlarm(root), isHistorized, historianTagname, isArray, arrayLength, historianReadOnly);
|
||||
}
|
||||
catch (JsonException)
|
||||
{
|
||||
@@ -57,6 +68,30 @@ public sealed record TagConfigIntent(
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// True when <paramref name="tagConfig"/> is a JSON object whose <c>historianReadOnly</c> key is present with a
|
||||
/// value that is not a JSON boolean (e.g. the string <c>"true"</c>). <see cref="Parse"/> reads such a value as
|
||||
/// <see langword="false"/> — an OWNED tag that gets provisioned — so the deploy gate refuses it instead
|
||||
/// (lmxopcua#899). Never throws; malformed JSON ⇒ <see langword="false"/> (other rules report that).
|
||||
/// </summary>
|
||||
/// <param name="tagConfig">The tag's raw <c>TagConfig</c> JSON.</param>
|
||||
/// <returns><see langword="true"/> when the key is present and not a boolean.</returns>
|
||||
public static bool HasMalformedHistorianReadOnly(string? tagConfig)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(tagConfig)) return false;
|
||||
try
|
||||
{
|
||||
using var doc = JsonDocument.Parse(tagConfig);
|
||||
return doc.RootElement.ValueKind == JsonValueKind.Object
|
||||
&& doc.RootElement.TryGetProperty(HistorianReadOnlyKey, out var el)
|
||||
&& el.ValueKind is not (JsonValueKind.True or JsonValueKind.False);
|
||||
}
|
||||
catch (JsonException)
|
||||
{
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
private static TagAlarmIntent? ParseAlarm(JsonElement root)
|
||||
{
|
||||
if (!root.TryGetProperty("alarm", out var a) || a.ValueKind != JsonValueKind.Object) return null;
|
||||
|
||||
@@ -37,6 +37,7 @@ public static class DraftValidator
|
||||
// and ValidateGalaxyTagFullName (blob-as-identity gone) are replaced by:
|
||||
ValidateRawNameCharset(draft, errors);
|
||||
ValidateHistorizedTagnameLength(draft, errors);
|
||||
ValidateHistorianReadOnly(draft, errors);
|
||||
ValidateUnsEffectiveLeafUniqueness(draft, errors);
|
||||
ValidateEquipReferenceResolution(draft, errors);
|
||||
ValidateCalculationTags(draft, errors);
|
||||
@@ -720,6 +721,21 @@ public static class DraftValidator
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>lmxopcua#899: <c>historianReadOnly</c> must be a JSON boolean. The runtime parse
|
||||
/// (<see cref="TagConfigIntent.Parse"/>) honours only a bool <c>true</c>, so a string <c>"true"</c> would deploy as an
|
||||
/// OWNED tag — provisioned (<c>EnsureTags</c>, an upsert) and recorded into — exactly what the author asked not to
|
||||
/// happen to a historian tag OtOpcUa does not own. A deploy error, never a silent "owned".</summary>
|
||||
private static void ValidateHistorianReadOnly(DraftSnapshot draft, List<ValidationError> errors)
|
||||
{
|
||||
foreach (var t in draft.Tags)
|
||||
{
|
||||
if (!TagConfigIntent.HasMalformedHistorianReadOnly(t.TagConfig)) continue;
|
||||
errors.Add(new("HistorianReadOnlyInvalid",
|
||||
$"tag '{t.TagId}' TagConfig '{TagConfigIntent.HistorianReadOnlyKey}' must be a JSON boolean (true or false)",
|
||||
t.TagId));
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>v3: within an equipment, the EFFECTIVE leaf name must be unique across its UnsTagReferences
|
||||
/// (DisplayNameOverride else the backing raw tag's Name), its VirtualTags (Name), and its ScriptedAlarms
|
||||
/// (Name) — the three share the equipment's UNS NodeId space (<c>{EquipmentId}/{EffectiveName}</c>).
|
||||
|
||||
@@ -0,0 +1,58 @@
|
||||
namespace ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
|
||||
/// <summary>
|
||||
/// Resolves a raw tag's authored <c>DataType</c> string to the <see cref="DriverDataType"/> the historian
|
||||
/// provisioning contract (<see cref="HistorianTagProvisionRequest"/>) carries (lmxopcua#898).
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <c>Tag.DataType</c> holds <b>OPC UA built-in type names</b> — what the AdminUI writes (<c>RawTagModal</c>,
|
||||
/// manual entry, CSV import, <c>RawBrowseCommitMapper</c>) and what <c>OtOpcUaNodeManager.ResolveBuiltInDataType</c>
|
||||
/// understands: <c>Float</c>, <c>Double</c>, <c>Byte</c>, <c>SByte</c>, … The provisioning hook used to
|
||||
/// <c>Enum.TryParse<DriverDataType></c> that string, which knows <c>Float32</c>/<c>Float64</c> but not
|
||||
/// <c>Float</c>/<c>Double</c>, and has no <c>Byte</c>/<c>SByte</c> member, so historized Float, Double, Byte and
|
||||
/// SByte tags were silently never provisioned.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Mapping (case-insensitive, trimmed):
|
||||
/// <list type="bullet">
|
||||
/// <item><c>Float</c> ⇒ <see cref="DriverDataType.Float32"/>, <c>Double</c> ⇒ <see cref="DriverDataType.Float64"/>.</item>
|
||||
/// <item><c>Byte</c> (0..255) and <c>SByte</c> (−128..127) ⇒ <see cref="DriverDataType.Int16"/>: a lossless
|
||||
/// widening (HistorianGateway's lossless-cast-or-reject rule). Int16 provisions as the historian's
|
||||
/// <c>Int2</c>, the type Boolean already uses; the historian's one-byte <c>Int1</c> creation is
|
||||
/// server-degenerate (#441) and its <c>UInt2</c> write path is the one OtOpcUa still widens away from.</item>
|
||||
/// <item>The other OPC UA names that share a <see cref="DriverDataType"/> member name (<c>Boolean</c>,
|
||||
/// <c>Int16</c>…<c>UInt64</c>, <c>String</c>, <c>DateTime</c>) map to that member.</item>
|
||||
/// <item>A <see cref="DriverDataType"/> member name (<c>Float32</c>, <c>Float64</c>, <c>Reference</c>) is still
|
||||
/// accepted, as before.</item>
|
||||
/// <item>Anything else (<c>Guid</c>, <c>ByteString</c>, a number, blank) is unresolved: the caller skips the tag.</item>
|
||||
/// </list>
|
||||
/// Whether a resolved type is then historizable is the backend's decision (the Gateway skips
|
||||
/// String/DateTime/Reference and the 64-bit integers; the SQL backends take every type).
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public static class HistorianDataTypeNames
|
||||
{
|
||||
/// <summary>Resolves an authored tag data type name to the provisioning <see cref="DriverDataType"/>.</summary>
|
||||
/// <param name="dataType">The tag's <c>DataType</c> string (an OPC UA built-in name, or a <see cref="DriverDataType"/> name).</param>
|
||||
/// <param name="driverDataType">The resolved type when the method returns <see langword="true"/>.</param>
|
||||
/// <returns><see langword="true"/> when the name resolves; <see langword="false"/> for an unknown, numeric or blank name.</returns>
|
||||
public static bool TryResolve(string? dataType, out DriverDataType driverDataType)
|
||||
{
|
||||
driverDataType = default;
|
||||
var name = dataType?.Trim();
|
||||
if (string.IsNullOrEmpty(name)) return false;
|
||||
|
||||
switch (name.ToUpperInvariant())
|
||||
{
|
||||
case "FLOAT": driverDataType = DriverDataType.Float32; return true;
|
||||
case "DOUBLE": driverDataType = DriverDataType.Float64; return true;
|
||||
case "BYTE":
|
||||
case "SBYTE": driverDataType = DriverDataType.Int16; return true;
|
||||
}
|
||||
|
||||
// Enum.TryParse also accepts a bare number ("3") or a comma list — neither is a type name.
|
||||
if (!char.IsLetter(name[0]) || name.Contains(',')) return false;
|
||||
return Enum.TryParse(name, ignoreCase: true, out driverDataType) && Enum.IsDefined(driverDataType);
|
||||
}
|
||||
}
|
||||
@@ -47,8 +47,10 @@ public sealed record HistorianTagProvisionRequest(
|
||||
/// </summary>
|
||||
/// <param name="Requested">Total tags submitted.</param>
|
||||
/// <param name="Ensured">Tags the historian acknowledged as created or already present.</param>
|
||||
/// <param name="Skipped">Tags whose data type is not historizable on the backend (never sent).</param>
|
||||
/// <param name="Failed">Tags that were sent but the backend did not acknowledge (incl. a swallowed transport error).</param>
|
||||
/// <param name="Skipped">Tags never sent: a data type the backend cannot historize, or (Gateway
|
||||
/// <c>ServerHistorian:ProvisionTags=CreateOnly</c>, lmxopcua#899) a tag that already exists and is left unchanged.</param>
|
||||
/// <param name="Failed">Tags that were sent but the backend did not acknowledge (incl. a swallowed transport error), or —
|
||||
/// under <c>CreateOnly</c> — whose existence lookup failed, so they were not sent.</param>
|
||||
public sealed record HistorianProvisionResult(
|
||||
int Requested,
|
||||
int Ensured,
|
||||
|
||||
Reference in New Issue
Block a user