Joseph Doherty
32f26272ae
Five tools under one repo, all docs organized per DOCS-GUIDE.md: - aalogcli: .NET 4.8 / x86 CliFx CLI for reading System Platform binary logs (*.aaLGX) for LLM debugging, built on aaOpenSource/aaLog. Commands: last, tail, range, unread, fields. Stable JSON envelope under --llm-json. Build template under lib/build/ for rebuilding aaLogReader.dll. - aot: ArchestrA Object Toolkit 2014 v4.0 reference material. Dev guide (Markdown converted from CHM), API reference for the ArchestrA.Toolkit namespace, and the Monitor / Watchdog VS sample solutions. - graccesscli: .NET 4.8 / x86 CliFx CLI that automates Galaxy configuration via the ArchestrA GRAccess COM interop. Includes session daemon, IPC protocol, and llm-json envelope contract. - grdb: SQL/DDL exploration of the Galaxy Repository database. DDL captures, reusable queries, hierarchy / contained-name <-> tag-name translation notes. - histdb: LLM-oriented reference for AVEVA Historian retrieval. INSQL linked-server, extension tables, every wwXxx time-domain extension, every retrieval mode, alarm/event SQL recipes, REST API. Distilled from the 243-page Historian Retrieval Guide. Root contains: - CLAUDE.md: thin index pointing into each tool's README. - DOCS-GUIDE.md: doctrine for organizing docs for LLM consumption. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
271 lines
11 KiB
Markdown
271 lines
11 KiB
Markdown
# Editing Template Attributes
|
|
|
|
This guide describes how to edit template attributes for an existing GRAccess template such as `TestMachine`.
|
|
|
|
Read `attribute-parsing.md` first so you know the exact attribute names and current settings before changing anything.
|
|
|
|
Run commands from `graccess_cli`. Examples assume an active session:
|
|
|
|
```powershell
|
|
graccess session start --galaxy ZB --node .
|
|
```
|
|
|
|
Without a session, add `--node .` to each command.
|
|
|
|
For LLM-driven edits, use `--llm-json` and validate first:
|
|
|
|
```powershell
|
|
graccess object snapshot --galaxy ZB --name TestMachine --type template --llm-json
|
|
graccess object attribute value set --galaxy ZB --name TestMachine --type template --attribute Description --value Updated --data-type string --confirm --confirm-target TestMachine --dry-run --llm-json
|
|
```
|
|
|
|
## Edit Flow
|
|
|
|
Wrap attribute edits in the standard GRAccess object edit flow:
|
|
|
|
```powershell
|
|
graccess object checkout --galaxy ZB --name TestMachine --type template --confirm --confirm-target TestMachine
|
|
|
|
# Attribute mutation commands.
|
|
|
|
graccess object save --galaxy ZB --name TestMachine --type template --confirm --confirm-target TestMachine
|
|
graccess object checkin --galaxy ZB --name TestMachine --type template --comment 'Edit template attributes' --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
If any mutation fails, do not continue with more changes until the failure is understood. Use `object undo-checkout` when the edit should be discarded.
|
|
|
|
## Confirm The Target Attribute
|
|
|
|
Before editing a specific attribute:
|
|
|
|
```powershell
|
|
graccess object attribute get --galaxy ZB --name TestMachine --type template --attribute Description --json
|
|
```
|
|
|
|
For setting-family edits, find candidate names first:
|
|
|
|
```powershell
|
|
graccess object attributes --galaxy ZB --name TestMachine --type template --json
|
|
graccess object attributes --galaxy ZB --name TestMachine --type template --configurable --json
|
|
graccess object extended-attributes --galaxy ZB --name TestMachine --type template --json
|
|
```
|
|
|
|
## Set Attribute Values
|
|
|
|
Use `object attribute set`:
|
|
|
|
```powershell
|
|
graccess object attribute set --galaxy ZB --name TestMachine --type template --attribute Description --value 'Updated description' --data-type string --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
Supported `--data-type` values:
|
|
|
|
| Data type | Conversion |
|
|
|---|---|
|
|
| `string` | `MxValue.PutString(...)` |
|
|
| `bool`, `boolean`, `mxboolean` | `MxValue.PutBoolean(...)` |
|
|
| `int`, `integer`, `mxinteger` | `MxValue.PutInteger(...)` |
|
|
| `float`, `mxfloat` | `MxValue.PutFloat(...)` |
|
|
| `double`, `mxdouble` | `MxValue.PutDouble(...)` |
|
|
|
|
Examples:
|
|
|
|
```powershell
|
|
graccess object attribute set --galaxy ZB --name TestMachine --type template --attribute EnableFeature --value true --data-type bool --confirm --confirm-target TestMachine
|
|
|
|
graccess object attribute set --galaxy ZB --name TestMachine --type template --attribute ScanPeriod --value 1000 --data-type int --confirm --confirm-target TestMachine
|
|
|
|
graccess object attribute set --galaxy ZB --name TestMachine --type template --attribute Gain --value 1.25 --data-type double --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
The current CLI does not support array values, time values, references, or complex `MxValue` payloads. Use export/import or extend `CreateMxValue(...)` when those are needed.
|
|
|
|
## Lock Or Unlock Attributes
|
|
|
|
Use `object attribute lock`:
|
|
|
|
```powershell
|
|
graccess object attribute lock --galaxy ZB --name TestMachine --type template --attribute Description --locked MxPropertyUnlocked --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
The `--locked` value must match a local `MxPropertyLockedEnum` member. The enum parser is case-insensitive and also accepts values with or without a `galaxy_` prefix when such a prefix exists.
|
|
|
|
## Change Attribute Security
|
|
|
|
Use `object attribute security`:
|
|
|
|
```powershell
|
|
graccess object attribute security --galaxy ZB --name TestMachine --type template --attribute Description --security MxSecurityOperate --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
The `--security` value must match a local `MxSecurityClassification` member.
|
|
|
|
## Change Attribute Buffer Flag
|
|
|
|
Use `object attribute buffer`:
|
|
|
|
```powershell
|
|
graccess object attribute buffer --galaxy ZB --name TestMachine --type template --attribute Description --has-buffer --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
To clear the flag, omit `--has-buffer`:
|
|
|
|
```powershell
|
|
graccess object attribute buffer --galaxy ZB --name TestMachine --type template --attribute Description --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
## Add A UDA
|
|
|
|
Use `object uda add`:
|
|
|
|
```powershell
|
|
graccess object uda add --galaxy ZB --name TestMachine --type template --uda CustomCode --data-type MxString --category MxCategoryWriteable_USC --security MxSecurityUndefined --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
Array UDA:
|
|
|
|
```powershell
|
|
graccess object uda add --galaxy ZB --name TestMachine --type template --uda CustomArray --data-type MxString --category MxCategoryWriteable_USC --security MxSecurityUndefined --is-array --array-count 10 --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
## Rename, Update, Or Delete A UDA
|
|
|
|
Rename:
|
|
|
|
```powershell
|
|
graccess object uda rename --galaxy ZB --name TestMachine --type template --uda CustomCode --new-name CustomCode2 --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
Update metadata:
|
|
|
|
```powershell
|
|
graccess object uda update --galaxy ZB --name TestMachine --type template --uda CustomCode2 --data-type MxString --category MxCategoryWriteable_USC --security MxSecurityUndefined --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
Delete:
|
|
|
|
```powershell
|
|
graccess object uda delete --galaxy ZB --name TestMachine --type template --uda CustomCode2 --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
## Edit Extensions
|
|
|
|
Use extension commands only when you know the supported extension type and primitive name for the template.
|
|
|
|
```powershell
|
|
graccess object extension add --galaxy ZB --name TestMachine --type template --extension-type ScriptExtension --primitive OnScan --object-extension --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
```powershell
|
|
graccess object extension rename --galaxy ZB --name TestMachine --type template --extension-type ScriptExtension --primitive OnScan --new-name OnScan2 --object-extension --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
```powershell
|
|
graccess object extension delete --galaxy ZB --name TestMachine --type template --extension-type ScriptExtension --primitive OnScan2 --object-extension --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
## Edit History Settings
|
|
|
|
History settings are usually stored as attributes or extension attributes. First identify candidate names:
|
|
|
|
```powershell
|
|
$attrs = graccess object attributes --galaxy ZB --name TestMachine --type template --json | ConvertFrom-Json
|
|
$extended = graccess object extended-attributes --galaxy ZB --name TestMachine --type template --json | ConvertFrom-Json
|
|
$history = (@($attrs) + @($extended)) | Where-Object {
|
|
$_.Name -match '(?i)hist|history|historian|storage|trend'
|
|
} | Sort-Object Name -Unique
|
|
|
|
$history | Select-Object Name, DataType, Category, Locked
|
|
```
|
|
|
|
Then edit a known setting with `object attribute set`, lock, security, or buffer commands. Example:
|
|
|
|
```powershell
|
|
graccess object attribute set --galaxy ZB --name TestMachine --type template --attribute HistoryEnabled --value true --data-type bool --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
If the setting value is not a simple string/bool/int/float/double, use export/import or extend CLI value serialization first.
|
|
|
|
## Edit I/O Settings
|
|
|
|
I/O settings may be attributes, object-reference assignments, or extension payloads.
|
|
|
|
Find likely attributes:
|
|
|
|
```powershell
|
|
$io = (@($attrs) + @($extended)) | Where-Object {
|
|
$_.Name -match '(?i)\bio\b|input|output|source|destination|scan|topic|device|address|reference'
|
|
} | Sort-Object Name -Unique
|
|
|
|
$io | Select-Object Name, DataType, Category, RuntimeSetHandler, ConfigSetHandler
|
|
```
|
|
|
|
Edit simple attribute-backed settings:
|
|
|
|
```powershell
|
|
graccess object attribute set --galaxy ZB --name TestMachine --type template --attribute ScanPeriod --value 1000 --data-type int --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
Edit object-level assignment properties with `object set` when applicable:
|
|
|
|
```powershell
|
|
graccess object set --galaxy ZB --name TestMachine --type template --property host --value AppEngine_001 --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
If the COM setter requires an object reference instead of a string, extend the CLI to resolve the named object and assign that object.
|
|
|
|
## Edit Alarm Settings
|
|
|
|
Alarm settings are commonly attribute-backed.
|
|
|
|
Find likely alarm attributes:
|
|
|
|
```powershell
|
|
$alarm = (@($attrs) + @($extended)) | Where-Object {
|
|
$_.Name -match '(?i)alarm|alert|limit|priority|severity|deadband|deviation|rate|roc|hihi|lolo|(^|[._])hi($|[._])|(^|[._])lo($|[._])|ack'
|
|
} | Sort-Object Name -Unique
|
|
|
|
$alarm | Select-Object Name, DataType, Category, SecurityClassification, Locked
|
|
```
|
|
|
|
Edit simple value-backed settings:
|
|
|
|
```powershell
|
|
graccess object attribute set --galaxy ZB --name TestMachine --type template --attribute AlarmPriority --value 500 --data-type int --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
Security and lock changes use the same attribute commands:
|
|
|
|
```powershell
|
|
graccess object attribute security --galaxy ZB --name TestMachine --type template --attribute AlarmPriority --security MxSecurityOperate --confirm --confirm-target TestMachine
|
|
graccess object attribute lock --galaxy ZB --name TestMachine --type template --attribute AlarmPriority --locked MxPropertyLocked --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
## Verify Attribute Edits
|
|
|
|
After checkin, re-read the edited metadata:
|
|
|
|
```powershell
|
|
graccess object attribute get --galaxy ZB --name TestMachine --type template --attribute Description --json
|
|
graccess object attributes --galaxy ZB --name TestMachine --type template --configurable --json
|
|
```
|
|
|
|
The current CLI does not read back attribute values, so value verification requires one of:
|
|
|
|
| Need | Path |
|
|
|---|---|
|
|
| Confirm metadata changed | `object attribute get` or `object attributes` |
|
|
| Confirm simple value changed | Add value readback support |
|
|
| Confirm full vendor configuration | Export object and compare package content with vendor tooling |
|
|
|
|
## Recommended CLI Extension For Full Attribute Editing
|
|
|
|
To fully support history, I/O, alarm, and script-related settings as first-class CLI operations, add:
|
|
|
|
```text
|
|
graccess object attribute value get --galaxy ZB --name TestMachine --type template --attribute AttrName --json
|
|
graccess object attribute value set --galaxy ZB --name TestMachine --type template --attribute AttrName --value-json file.json --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
The implementation should serialize `IAttribute.Value` defensively and support complex `MxValue` shapes beyond the current scalar `string`, `bool`, `int`, `float`, and `double` conversions.
|