docs(secured-writes): design — tag selector + data-type auto-fill from MxGateway browse
This commit is contained in:
Joseph Doherty
@@ -0,0 +1,171 @@
|
||||
# Secured Writes — Tag Selector + Data-Type Auto-Fill (Design)
|
||||
|
||||
**Date:** 2026-06-27
|
||||
**Component(s):** Central UI (#9), Data Connection Layer (#4); Security & Auth (#10) for the Secured Writes UX.
|
||||
**Status:** Approved design — ready for implementation plan.
|
||||
|
||||
## Problem
|
||||
|
||||
On the Central UI Secured Writes page (`/operations/secured-writes`), an Operator submits a
|
||||
two-person MxGateway secured write. Today the **Tag path** is a free-text input and the **Data
|
||||
type** is a manually-chosen dropdown defaulting to `Boolean`. Operators must know the exact
|
||||
MxGateway tag reference and the correct data type by hand — error-prone, and a wrong data type
|
||||
only surfaces at *approval* time (the value can't be decoded/written).
|
||||
|
||||
We want:
|
||||
1. The **Tag path** field to be backed by a **tag selector** (browse the connection's tags).
|
||||
2. The **Data type** to be **auto-selected from the chosen tag**.
|
||||
|
||||
## Key insight — the data type is already available
|
||||
|
||||
Secured writes are **MxGateway-only** (the page filters connections to `Protocol == "MxGateway"`,
|
||||
and the ManagementActor enforces the same on submit). The MxGateway gateway *already returns* a
|
||||
per-attribute `data_type_name` (free-form Galaxy text, e.g. `"Float"`, `"Integer"`, `"Boolean"`)
|
||||
on its browse response (`GalaxyAttribute.data_type_name` in `galaxy_repository.proto`). ScadaBridge
|
||||
currently **discards** it: `RealMxGatewayClient.BrowseChildrenAsync` reads only
|
||||
`FullTagReference` + `AttributeName` when building `MxBrowseChild`.
|
||||
|
||||
So the feature is mostly *plumbing an existing value through* + reusing the existing
|
||||
`NodeBrowserDialog`. No new gRPC, no DB/schema/migration, no new cross-cluster message contracts.
|
||||
|
||||
Reused as-is:
|
||||
- `NodeBrowserDialog` / `TreeRow` tag browser (already used by `InstanceConfigure`,
|
||||
`TestBindingsDialog`).
|
||||
- The full browse call path: `IBrowseService` → `CommunicationService.BrowseNodeAsync` →
|
||||
`SiteCommunicationActor` → `DeploymentManager` → `DataConnectionManagerActor` →
|
||||
`DataConnectionActor` → adapter.
|
||||
- `BrowseNode` already carries an optional `DataType` field.
|
||||
|
||||
## UX decisions (confirmed)
|
||||
|
||||
- **Tag field:** editable text field **+ a "Browse…" button** (hybrid, matching
|
||||
`InstanceConfigure`). Operators can still paste a known reference; the browser populates the field.
|
||||
- **Data type:** **auto-filled from the tag but left editable**. The Galaxy type name is free-form;
|
||||
the map to ScadaBridge's `DataType` enum is best-effort, so an unmapped type must leave the
|
||||
operator able to choose.
|
||||
|
||||
## Design
|
||||
|
||||
### Layer 1 — Surface `DataType` from MxGateway browse (DCL)
|
||||
|
||||
- `Adapters/IMxGatewayClient.cs`: extend the seam record additively —
|
||||
`record MxBrowseChild(string NodeId, string DisplayName, BrowseNodeClass NodeClass, bool HasChildren, string? DataType = null)`.
|
||||
- `Adapters/RealMxGatewayClient.cs` (`BrowseChildrenAsync`): when projecting
|
||||
`parentObject.Attributes`, pass `attr.DataTypeName` (normalise empty → `null`) into `MxBrowseChild`.
|
||||
- `Adapters/MxGatewayDataConnection.cs`: forward it —
|
||||
`new BrowseNode(c.NodeId, c.DisplayName, c.NodeClass, c.HasChildren, DataType: c.DataType)`.
|
||||
- Test fake `FakeMxGatewayClient`: update to the new record shape and emit a sample `DataType` so
|
||||
tests can assert end-to-end surfacing.
|
||||
|
||||
`ValueRank`/`Writable` remain `null` for MxGateway (not needed here). Array attributes
|
||||
(`is_array`/`array_dimension`) are **explicitly out of scope** — a secured write to an array via
|
||||
this form is an edge case; the operator can pick `List` manually.
|
||||
|
||||
### Layer 2 — Let the browser emit the full node (shared dialog)
|
||||
|
||||
`NodeBrowserDialog` currently emits only `OnSelected(string nodeId)`. Add, additively:
|
||||
- `EventCallback<BrowseNode> OnNodeSelected` — invoked alongside the existing `OnSelected` in
|
||||
`SelectBrowseNode()`. The internal tree node retains its source `BrowseNode` so the emit is
|
||||
faithful (NodeId + DataType). Existing callers are unaffected (the callback is optional).
|
||||
- `bool ShowSearch = true` — set `false` from Secured Writes. MxGateway does **not** implement
|
||||
`IAddressSpaceSearchable`, so the search box would always return a `NotBrowsable` failure;
|
||||
hiding it avoids a guaranteed-broken affordance. Default `true` keeps OPC UA callers unchanged.
|
||||
|
||||
### Layer 3 — Wire the form (`Components/Pages/Operations/SecuredWrites.razor`)
|
||||
|
||||
- Tag path becomes an input-group: the existing editable `<input>` + a `Browse…` button,
|
||||
`disabled` unless a site **and** an MxGateway connection are selected
|
||||
(`CanBrowse`, mirroring `InstanceConfigure`'s `canBrowse`).
|
||||
- Render one `<NodeBrowserDialog @ref="_browserRef" SiteId="@_formSiteIdentifier"
|
||||
ConnectionName="@_formConnectionName" ShowSearch="false" OnNodeSelected="OnTagPicked" />`.
|
||||
- `OpenBrowser()` → `await _browserRef.ShowAsync(_formSiteIdentifier, _formConnectionName, _formTagPath)`
|
||||
(seeds with whatever is already typed).
|
||||
- `OnTagPicked(BrowseNode node)`:
|
||||
```csharp
|
||||
_formTagPath = node.NodeId;
|
||||
if (SecuredWriteDataTypeMapper.TryMap(node.DataType, out var dt))
|
||||
_formValueType = dt.ToString();
|
||||
// else: leave _formValueType unchanged — operator picks
|
||||
```
|
||||
- The Data type `<select>` is unchanged (no `disabled`): pre-filled but editable. `CanSubmit`
|
||||
is unchanged.
|
||||
|
||||
### Layer 4 — Galaxy type → `DataType` mapping
|
||||
|
||||
A small internal, unit-testable static class in CentralUI. Case-insensitive, whitespace-trimmed:
|
||||
|
||||
| Galaxy `data_type_name` | ScadaBridge `DataType` |
|
||||
| --- | --- |
|
||||
| `boolean`, `bool` | `Boolean` |
|
||||
| `integer`, `int`, `int32` | `Int32` |
|
||||
| `float` | `Float` |
|
||||
| `double` | `Double` |
|
||||
| `string` | `String` |
|
||||
| `time` | `DateTime` |
|
||||
| anything else / null / empty | *no map — operator's selection kept* |
|
||||
|
||||
```csharp
|
||||
internal static class SecuredWriteDataTypeMapper
|
||||
{
|
||||
public static bool TryMap(string? galaxyTypeName, out DataType dataType)
|
||||
{
|
||||
dataType = default;
|
||||
if (string.IsNullOrWhiteSpace(galaxyTypeName)) return false;
|
||||
switch (galaxyTypeName.Trim().ToLowerInvariant())
|
||||
{
|
||||
case "boolean": case "bool": dataType = DataType.Boolean; return true;
|
||||
case "integer": case "int": case "int32": dataType = DataType.Int32; return true;
|
||||
case "float": dataType = DataType.Float; return true;
|
||||
case "double": dataType = DataType.Double; return true;
|
||||
case "string": dataType = DataType.String; return true;
|
||||
case "time": dataType = DataType.DateTime; return true;
|
||||
default: return false;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`Binary` and `List` are intentionally not auto-mapped (no clean Galaxy source); operator picks them.
|
||||
|
||||
## Error handling / edge cases
|
||||
|
||||
- Browse button disabled until site + MxGateway connection chosen.
|
||||
- Gateway returns no type (older gateway / read gap) → `DataType` null → mapper returns false →
|
||||
dropdown keeps its value; operator picks. Graceful.
|
||||
- Unmapped Galaxy type → same graceful fallback; auto-fill stays editable so a mis-map is fixable.
|
||||
- MxGateway search box hidden (`ShowSearch=false`) — tree browse + expand only.
|
||||
|
||||
## Testing
|
||||
|
||||
- **Unit:** `SecuredWriteDataTypeMapper` — every known name (incl. casing/whitespace) → expected
|
||||
enum; `null` / `""` / exotic → `false`.
|
||||
- **DCL:** assert a browsed MxGateway attribute's `DataTypeName` survives to `BrowseNode.DataType`
|
||||
through `MxGatewayDataConnection` (via the updated `FakeMxGatewayClient`).
|
||||
- **Build + targeted tests** for touched projects (DCL, DCL tests, CentralUI) — not the full suite.
|
||||
- **Live-smoke:** rebuild the image (`bash docker/deploy.sh`) and exercise the page against an
|
||||
MxGateway connection.
|
||||
|
||||
## Docs to update (spec travels with code)
|
||||
|
||||
- Secured Writes section under **Security & Auth** — tag selector + data-type auto-fill UX.
|
||||
- MxGateway browse **type-info** note under **Data Connection Layer** — `DataType` now surfaced
|
||||
for MxGateway (previously OPC-UA-only).
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Array attribute handling (`is_array`) → `List`.
|
||||
- OPC UA / non-MxGateway connections (Secured Writes is MxGateway-only).
|
||||
- MxGateway address-space search (adapter does not implement `IAddressSpaceSearchable`).
|
||||
- Any DB schema, migration, or new message contract (`ValueType` already exists on
|
||||
`SubmitSecuredWriteCommand`).
|
||||
|
||||
## Files touched
|
||||
|
||||
- `src/ZB.MOM.WW.ScadaBridge.DataConnectionLayer/Adapters/IMxGatewayClient.cs`
|
||||
- `src/ZB.MOM.WW.ScadaBridge.DataConnectionLayer/Adapters/RealMxGatewayClient.cs`
|
||||
- `src/ZB.MOM.WW.ScadaBridge.DataConnectionLayer/Adapters/MxGatewayDataConnection.cs`
|
||||
- `FakeMxGatewayClient` (DCL test fake)
|
||||
- `src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Dialogs/NodeBrowserDialog.razor`
|
||||
- `src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Pages/Operations/SecuredWrites.razor`
|
||||
- new `SecuredWriteDataTypeMapper` + unit test
|
||||
- Component design docs (Security & Auth, Data Connection Layer)
|
||||
Reference in New Issue
Block a user