From da277a843a3255cf5c3c08ff79085b5ff90a0639 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Wed, 29 Apr 2026 22:40:31 -0400 Subject: [PATCH] docs: provisioning recipes for parity rig via graccess-cli MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Calls out the single-platform constraint on this dev box and the graccess-cli at C:\Users\dohertj2\Desktop\graccess as the way to configure the rest of the parity-rig Galaxy shape: - ScanState probe parity (multi-platform) is deferred to a customer rig — not feasible on this dev box. PR 7.2 gate accepts "n/a, deferred" on those rows because PR 4.7's unit tests already pin the state-decoder + member-tracking logic. - Per-row provisioning recipes for the five ⚙-scriptable rows: FreeAccess/Operate UDA, Configure/Tune UDA, value-change source (recommend external write-loop over template surgery), $Alarm* extension, History extension. All against a reserved OtOpcUaParityTest sandbox UDO so plant-relevant objects stay untouched. - Trailing deploy + Galaxy.Host restart so MxAccess picks up the change before re-running the matrix. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/v2/Galaxy.ParityRig.md | 146 +++++++++++++++++++++++++++++++++--- 1 file changed, 134 insertions(+), 12 deletions(-) diff --git a/docs/v2/Galaxy.ParityRig.md b/docs/v2/Galaxy.ParityRig.md index b8ffc0a..a718abe 100644 --- a/docs/v2/Galaxy.ParityRig.md +++ b/docs/v2/Galaxy.ParityRig.md @@ -130,19 +130,141 @@ row to: Skip-on-empty-shape scenarios fail-soft today. To turn a skip into a real result, the dev Galaxy needs the shape in the right column: -| Scenario | Needs | -|---|---| -| `BrowseAndReadParityTests` (3 tests) | Any deployed objects with attributes | -| `SubscribeAndEventRateParityTests` event-rate | ≥5 attributes whose values *change* in 3s | -| `WriteByClassificationParityTests` (FreeAccess/Operate) | A FreeAccess/Operate numeric attribute | -| `WriteByClassificationParityTests` (Configure/Tune) | A Configure/Tune attribute | -| `AlarmTransitionParityTests` (2 tests) | Attributes with the `$Alarm*` extension | -| `HistoryReadParityTests` (historized set) | Attributes with the History extension | -| `ScanStateProbeParityTests` (2 tests) | Multiple `$WinPlatform` / `$AppEngine` objects | +| Scenario | Needs | Local rig | +|---|---|---| +| `BrowseAndReadParityTests` (3 tests) | Any deployed objects with attributes | ✅ existing seed | +| `SubscribeAndEventRateParityTests` event-rate | ≥5 attributes whose values *change* in 3s | ⚙ scriptable via graccess-cli | +| `WriteByClassificationParityTests` (FreeAccess/Operate) | A FreeAccess/Operate numeric attribute | ⚙ scriptable via graccess-cli | +| `WriteByClassificationParityTests` (Configure/Tune) | A Configure/Tune attribute | ⚙ scriptable via graccess-cli | +| `AlarmTransitionParityTests` (2 tests) | Attributes with the `$Alarm*` extension | ⚙ scriptable via graccess-cli | +| `HistoryReadParityTests` (historized set) | Attributes with the History extension | ⚙ scriptable via graccess-cli | +| `ScanStateProbeParityTests` (2 tests) | Multiple `$WinPlatform` / `$AppEngine` objects | ❌ **deferred to customer rig** — this dev box is provisioned for one platform only | -The dev Galaxy from the existing E2E smoke (`gr/seed-phase-7-smoke.sql`) -covers most of these; the multi-platform scenario probably needs -hand-deploying a second `$WinPlatform` instance. +### The single-platform constraint + +The dev box at `DESKTOP-6JL3KKO` is licensed / configured for a single +deployed `$WinPlatform`. Adding a second platform isn't feasible here, +so `ScanStateProbeParityTests` will skip in a "no overlap" branch on +this rig. Both of its scenarios already handle that case gracefully +(`Assert.Skip("no overlapping platform hosts between backends — likely +the transport names differ but no $WinPlatform was discovered")`), so +the matrix reports them as **n/a (deferred)** rather than red. + +Plan: defer the two ScanState scenarios to a customer rig with multiple +platforms. The PR 7.2 gate accepts "n/a, deferred" on these rows +provided the legacy `GalaxyRuntimeProbeManager` and the in-process +`PerPlatformProbeWatcher` have matching unit-test coverage of the +state-decoder + member-tracking logic — which they do (PR 4.7's tests). +Treat the runtime parity check as a customer-rig acceptance gate before +that customer goes live, not a precondition for retiring the legacy +projects on this dev box. + +### Provisioning the rest via graccess-cli + +`C:\Users\dohertj2\Desktop\graccess\graccess_cli\` is a .NET Framework +4.8 console app over the ArchestrA GRAccess COM API. It can configure +templates, instances, attributes, UDAs, extensions, and attribute +security — i.e. every row above marked ⚙ scriptable. Full surface in +`graccess/graccess_cli/docs/usage.md` and per-area workflow guides +(`attribute-editing.md`, `template-editing.md`, +`template-instance-editing.md`). + +Reserve a sandbox UDO (e.g. `OtOpcUaParityTest`) to avoid mutating +attributes on plant-relevant objects. Concrete commands per requirement: + +**A FreeAccess/Operate numeric attribute** (covers WriteByClassification +FreeAccess/Operate scenario): + +```powershell +graccess object uda add ` + --galaxy ZB --name OtOpcUaParityTest --type template ` + --uda OperateValue --data-type MxFloat ` + --category MxCategoryWriteable_C --security MxSecurityOperate ` + --confirm --confirm-target OtOpcUaParityTest +``` + +**A Configure / Tune attribute** (covers WriteByClassification +Configure/Tune scenario): + +```powershell +# Tune +graccess object uda add ` + --galaxy ZB --name OtOpcUaParityTest --type template ` + --uda TuneValue --data-type MxFloat ` + --category MxCategoryWriteable_T --security MxSecurityTune ` + --confirm --confirm-target OtOpcUaParityTest + +# Configure +graccess object uda add ` + --galaxy ZB --name OtOpcUaParityTest --type template ` + --uda ConfigValue --data-type MxFloat ` + --category MxCategoryWriteable_C --security MxSecurityConfigure ` + --confirm --confirm-target OtOpcUaParityTest +``` + +**A changing-value attribute** (covers Subscribe event-rate scenario). +Two ways: + +1. *On-scan increment* — bind a script extension that bumps a counter + each scan. Simplest to author with `object extension add` against + `ScriptExtension` plus `object attribute set` for the script body + (see `attribute-editing.md` §"Edit Extensions" for the pattern). +2. *External writer loop* — leave the attribute as plain Float and run + a one-liner that writes incrementing values from the parity-test + shell. Uses the legacy backend path so it's available before the + mxgw subscriber is up. This keeps the Galaxy template clean. + +For first-pass validation pick #2 — no template surgery needed, and the +write loop runs only during `dotnet test`. + +**Attributes with the `$Alarm*` extension** (covers AlarmTransition +scenario). Per `attribute-editing.md` §"Edit Alarm Settings" the +likely-named attributes vary by extension type +(`Limit`, `RateOfChange`, etc.). Add the extension via: + +```powershell +graccess object extension add ` + --galaxy ZB --name OtOpcUaParityTest --type template ` + --extension-type AnalogLimitAlarm --primitive AlarmInput ` + --object-extension ` + --confirm --confirm-target OtOpcUaParityTest +``` + +Then set HiHi/Hi/Lo/LoLo limit values + priority on the resulting +attributes via `object attribute set`. Inspect first via +`object attributes` to see the names the extension introduces — they +differ across Aveva versions. + +**Attributes with the History extension** (covers HistoryRead routing +scenario). History settings are usually attribute or extension +attributes; `attribute-editing.md` §"Edit History Settings" covers the +discovery flow. Quick start: + +```powershell +graccess object extension add ` + --galaxy ZB --name OtOpcUaParityTest --type template ` + --extension-type HistoryExtension --primitive HistoryRecord ` + --object-extension ` + --confirm --confirm-target OtOpcUaParityTest + +# Then enable history on whichever attribute the extension points at +graccess object attribute set ` + --galaxy ZB --name OtOpcUaParityTest --type template ` + --attribute HistoryEnabled --value true --data-type bool ` + --confirm --confirm-target OtOpcUaParityTest +``` + +**Deploy + restart Galaxy.Host after any of the above** so MxAccess +sees the change: + +```powershell +graccess object deploy --galaxy ZB --name OtOpcUaParityTest_001 ` + --confirm --confirm-target OtOpcUaParityTest_001 +sc.exe restart OtOpcUaGalaxyHost +``` + +Then re-run the parity matrix. The previously-skipped scenarios should +now find a sandbox attribute matching their selector and assert. ## Soak run