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>
371 lines
17 KiB
Markdown
371 lines
17 KiB
Markdown
# Editing Existing Templates
|
|
|
|
This guide describes how to edit an existing GRAccess template such as `TestMachine` with `graccess_cli`.
|
|
|
|
Use this document as the top-level workflow. For deeper coverage, also read:
|
|
|
|
- `attribute-editing.md` - attribute values, locks, security, buffers, UDAs, extensions, and settings families such as history, I/O, and alarms.
|
|
- `script-editing.md` - script-library import/export and the current options for object-level script edits.
|
|
- `template-instance-editing.md` - create and edit instances from templates, including areas, engines, and I/O assignment.
|
|
- `template-parsing.md` - read-only inspection workflow to run before and after edits.
|
|
|
|
Run commands from `graccess_cli`. Examples assume the CLI is available as `graccess`. During local development, replace `graccess` with:
|
|
|
|
```powershell
|
|
dotnet run --project src/ZB.MOM.WW.GRAccess.Cli/ZB.MOM.WW.GRAccess.Cli.csproj --
|
|
```
|
|
|
|
## Safety Model
|
|
|
|
Every mutating command requires `--confirm`. Template/object mutation commands also require `--confirm-target` matching the exact object name being edited. File import/export commands use the file path as the confirmation target.
|
|
|
|
For template edits, use this pattern:
|
|
|
|
```powershell
|
|
--confirm --confirm-target TestMachine
|
|
```
|
|
|
|
For LLM-driven edits, validate the final command or batch plan before mutation:
|
|
|
|
```powershell
|
|
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
|
|
graccess batch --file plan.json --mode validate --llm-json
|
|
```
|
|
|
|
Do not edit production templates directly unless the target, backup, and rollback path are explicit. For risky work, derive or export a test copy first.
|
|
|
|
## Session Setup
|
|
|
|
Start a session for repeated edits:
|
|
|
|
```powershell
|
|
graccess session start --galaxy ZB --node .
|
|
```
|
|
|
|
With a session active, omit `--node` on logged-in commands:
|
|
|
|
```powershell
|
|
graccess object get --galaxy ZB --name TestMachine --type template --json
|
|
```
|
|
|
|
Use `object snapshot --llm-json` for before/after verification when an LLM is planning or executing the edit:
|
|
|
|
```powershell
|
|
graccess object snapshot --galaxy ZB --name TestMachine --type template --llm-json
|
|
```
|
|
|
|
Without a session, include `--node .` on each command.
|
|
|
|
## Pre-Edit Snapshot
|
|
|
|
Take a read-only snapshot before changing anything:
|
|
|
|
```powershell
|
|
$galaxy = 'ZB'
|
|
$name = 'TestMachine'
|
|
$out = ".\template-snapshots\$name-before"
|
|
New-Item -ItemType Directory -Force -Path $out | Out-Null
|
|
|
|
graccess object get --galaxy $galaxy --name $name --type template --json `
|
|
| Set-Content "$out\object.json"
|
|
|
|
graccess object attributes --galaxy $galaxy --name $name --type template --json `
|
|
| Set-Content "$out\attributes.json"
|
|
|
|
graccess object attributes --galaxy $galaxy --name $name --type template --configurable --json `
|
|
| Set-Content "$out\configurable-attributes.json"
|
|
|
|
graccess object extended-attributes --galaxy $galaxy --name $name --type template --json `
|
|
| Set-Content "$out\extended-attributes.json"
|
|
```
|
|
|
|
For a fuller snapshot, follow `template-parsing.md`, `attribute-parsing.md`, and `script-parsing.md`.
|
|
|
|
## Optional Backup Export
|
|
|
|
For a rollback artifact, export the template before editing:
|
|
|
|
```powershell
|
|
$pkg = '.\template-snapshots\TestMachine-before\TestMachine.aaPKG'
|
|
graccess objects export --galaxy ZB --type template --name TestMachine --output $pkg --confirm --confirm-target $pkg
|
|
```
|
|
|
|
`objects export` writes a file and therefore requires `--confirm-target` equal to the output path.
|
|
|
|
## Standard Edit Flow
|
|
|
|
GRAccess object changes should follow:
|
|
|
|
```text
|
|
CheckOut -> mutate -> Save -> CheckIn(comment)
|
|
```
|
|
|
|
With `graccess_cli`:
|
|
|
|
```powershell
|
|
graccess object checkout --galaxy ZB --name TestMachine --type template --confirm --confirm-target TestMachine
|
|
|
|
# Run one or more mutation commands here.
|
|
|
|
graccess object save --galaxy ZB --name TestMachine --type template --confirm --confirm-target TestMachine
|
|
graccess object checkin --galaxy ZB --name TestMachine --type template --comment 'Edited TestMachine' --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
If you need to discard changes:
|
|
|
|
```powershell
|
|
graccess object undo-checkout --galaxy ZB --name TestMachine --type template --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
`object unload` releases the object from the GRAccess cache:
|
|
|
|
```powershell
|
|
graccess object unload --galaxy ZB --name TestMachine --type template --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
## Edit Object Properties
|
|
|
|
Use `object set` for supported object-level properties:
|
|
|
|
| Property | Command value | Notes |
|
|
|---|---|---|
|
|
| Tagname | `tagname` | Renames the object tagname |
|
|
| Contained name | `contained-name` | Changes contained name |
|
|
| Area | `area` | Object reference or accepted GRAccess value |
|
|
| Host | `host` | Object reference or accepted GRAccess value |
|
|
| Container | `container` | Object reference or accepted GRAccess value |
|
|
| Toolset | `toolset` | Toolset reference or accepted GRAccess value |
|
|
| Security group | `security-group` | Security group reference or accepted GRAccess value |
|
|
|
|
Example:
|
|
|
|
```powershell
|
|
graccess object checkout --galaxy ZB --name TestMachine --type template --confirm --confirm-target TestMachine
|
|
graccess object set --galaxy ZB --name TestMachine --type template --property contained-name --value TestMachineEdited --confirm --confirm-target TestMachine
|
|
graccess object save --galaxy ZB --name TestMachine --type template --confirm --confirm-target TestMachine
|
|
graccess object checkin --galaxy ZB --name TestMachine --type template --comment 'Update contained name' --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
When renaming `tagname`, the command target is the current name. After a successful rename, use the new name for later commands:
|
|
|
|
```powershell
|
|
graccess object checkout --galaxy ZB --name TestMachine --type template --confirm --confirm-target TestMachine
|
|
graccess object set --galaxy ZB --name TestMachine --type template --property tagname --value TestMachineV2 --confirm --confirm-target TestMachine
|
|
graccess object save --galaxy ZB --name TestMachineV2 --type template --confirm --confirm-target TestMachineV2
|
|
graccess object checkin --galaxy ZB --name TestMachineV2 --type template --comment 'Rename template' --confirm --confirm-target TestMachineV2
|
|
```
|
|
|
|
Validate tagname renames in a test galaxy first. If the local GRAccess cache cannot find the object by the new name before `Save`, the CLI needs a combined rename/save/checkin command that keeps the same COM object reference for the full operation.
|
|
|
|
Object-reference properties such as area, host, container, toolset, and security group depend on what the local GRAccess COM property setter accepts. If a string value fails, extend the CLI to resolve the named target object first and assign the COM object instead of the raw string.
|
|
|
|
## Edit Attributes And Settings
|
|
|
|
Use `attribute-editing.md` for the full attribute workflow.
|
|
|
|
Common commands:
|
|
|
|
```powershell
|
|
graccess object attribute set --galaxy ZB --name TestMachine --type template --attribute Description --value 'Updated description' --data-type string --confirm --confirm-target TestMachine
|
|
|
|
graccess object attribute lock --galaxy ZB --name TestMachine --type template --attribute Description --locked MxPropertyUnlocked --confirm --confirm-target TestMachine
|
|
|
|
graccess object attribute security --galaxy ZB --name TestMachine --type template --attribute Description --security MxSecurityOperate --confirm --confirm-target TestMachine
|
|
|
|
graccess object attribute buffer --galaxy ZB --name TestMachine --type template --attribute Description --has-buffer --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
The current CLI supports attribute value types `string`, `bool`, `int`, `float`, and `double`.
|
|
|
|
History, I/O, alarm, and script settings are usually represented as attributes, extended attributes, object package content, or extension-specific payloads. For value-level edits beyond the current `object attribute set` support, use export/import or add CLI support for safe `IAttribute.Value` parsing and serialization.
|
|
|
|
## Edit UDAs
|
|
|
|
UDAs are object mutations and should be wrapped in checkout/save/checkin.
|
|
|
|
Add a UDA:
|
|
|
|
```powershell
|
|
graccess object checkout --galaxy ZB --name TestMachine --type template --confirm --confirm-target TestMachine
|
|
graccess object uda add --galaxy ZB --name TestMachine --type template --uda CustomCode --data-type MxString --category MxCategoryWriteable_USC --security MxSecurityUndefined --confirm --confirm-target TestMachine
|
|
graccess object save --galaxy ZB --name TestMachine --type template --confirm --confirm-target TestMachine
|
|
graccess object checkin --galaxy ZB --name TestMachine --type template --comment 'Add CustomCode UDA' --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
Rename a UDA:
|
|
|
|
```powershell
|
|
graccess object uda rename --galaxy ZB --name TestMachine --type template --uda CustomCode --new-name CustomCode2 --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
Update UDA 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 a UDA:
|
|
|
|
```powershell
|
|
graccess object uda delete --galaxy ZB --name TestMachine --type template --uda CustomCode2 --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
## Edit Extensions
|
|
|
|
Extension primitives are object mutations and should be wrapped in checkout/save/checkin.
|
|
|
|
Add an extension primitive:
|
|
|
|
```powershell
|
|
graccess object extension add --galaxy ZB --name TestMachine --type template --extension-type ScriptExtension --primitive OnScan --object-extension --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
Rename an extension primitive:
|
|
|
|
```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
|
|
```
|
|
|
|
Delete an extension primitive:
|
|
|
|
```powershell
|
|
graccess object extension delete --galaxy ZB --name TestMachine --type template --extension-type ScriptExtension --primitive OnScan2 --object-extension --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
Exact extension type and primitive names must match what the local System Platform installation and template support.
|
|
|
|
## Derive A Template
|
|
|
|
Derive a test template before editing a production template directly. This is also how you extend a base System Platform template, such as deriving `$TestMachine` from `$gMachine`.
|
|
|
|
```powershell
|
|
graccess template derive --galaxy ZB --name TestMachine --type template --new-name TestMachine_EditTest --create-contained --confirm --confirm-target TestMachine
|
|
```
|
|
|
|
Then edit `TestMachine_EditTest`:
|
|
|
|
```powershell
|
|
graccess object checkout --galaxy ZB --name TestMachine_EditTest --type template --confirm --confirm-target TestMachine_EditTest
|
|
```
|
|
|
|
To extend `$gMachine` with a new machine template:
|
|
|
|
```powershell
|
|
graccess template derive --galaxy ZB --name '$gMachine' --type template --new-name '$MyMachine' --confirm --confirm-target '$gMachine' --llm-json
|
|
graccess object snapshot --galaxy ZB --name '$MyMachine' --type template --llm-json
|
|
```
|
|
|
|
Use `--create-contained` only when the source template has contained templates/objects that should be copied into the derived template. For a family like `$TestMachine`, contained templates such as `$TestMachine.DelmiaReceiver` and `$TestMachine.MESReceiver` are part of the template design and should be verified after derivation:
|
|
|
|
```powershell
|
|
graccess template derive --galaxy ZB --name '$TestMachine' --type template --new-name '$MyMachine' --create-contained --confirm --confirm-target '$TestMachine' --llm-json
|
|
graccess template list --galaxy ZB --pattern '%MyMachine%' --llm-json
|
|
```
|
|
|
|
If the derived family does not include expected embedded templates, do not hand-edit production objects to compensate. Add or validate CLI support for contained template creation against a disposable test family first.
|
|
|
|
## Edit Embedded Template Objects
|
|
|
|
Contained templates are edited by targeting the contained template tagname. For the `TestMachine` family:
|
|
|
|
```powershell
|
|
graccess object snapshot --galaxy ZB --name '$TestMachine.DelmiaReceiver' --type template --llm-json
|
|
graccess object checkout --galaxy ZB --name '$TestMachine.DelmiaReceiver' --type template --confirm --confirm-target '$TestMachine.DelmiaReceiver'
|
|
graccess object attribute value set --galaxy ZB --name '$TestMachine.DelmiaReceiver' --type template --attribute DownloadPath --value 'C:\Recipes' --data-type string --confirm --confirm-target '$TestMachine.DelmiaReceiver' --llm-json
|
|
graccess object save --galaxy ZB --name '$TestMachine.DelmiaReceiver' --type template --confirm --confirm-target '$TestMachine.DelmiaReceiver'
|
|
graccess object checkin --galaxy ZB --name '$TestMachine.DelmiaReceiver' --type template --comment 'Update Delmia receiver download path' --confirm --confirm-target '$TestMachine.DelmiaReceiver'
|
|
```
|
|
|
|
Contained template edits flow to future instances and may affect derived/instantiated objects depending on lock and override state. Before editing an embedded template, snapshot representative existing child instances such as `DelmiaReceiver_001` and compare after checkin.
|
|
|
|
## Instantiate For Validation
|
|
|
|
Create a test instance from the edited template:
|
|
|
|
```powershell
|
|
graccess template instantiate --galaxy ZB --name TestMachine_EditTest --type template --new-name TestMachine_EditTest_001 --create-contained --confirm --confirm-target TestMachine_EditTest
|
|
```
|
|
|
|
Use instance deployment commands only against explicitly named test instances:
|
|
|
|
```powershell
|
|
graccess instance deploy --galaxy ZB --name TestMachine_EditTest_001 --type instance --confirm --confirm-target TestMachine_EditTest_001
|
|
```
|
|
|
|
## Edit Scripts
|
|
|
|
Use `script-editing.md` for script-library import/export and object-level script guidance.
|
|
|
|
The current CLI can import script libraries:
|
|
|
|
```powershell
|
|
graccess script-library import --galaxy ZB --path '.\scripts\CommonScripts.aaslib' --confirm --confirm-target '.\scripts\CommonScripts.aaslib'
|
|
```
|
|
|
|
The current CLI does not expose direct JSON editing for object-level script bodies. Use object export/import for full-fidelity script body edits, or add a dedicated command that exposes script primitives and script-valued attributes.
|
|
|
|
## Post-Edit Verification
|
|
|
|
After checkin, take a second snapshot:
|
|
|
|
```powershell
|
|
$galaxy = 'ZB'
|
|
$name = 'TestMachine'
|
|
$out = ".\template-snapshots\$name-after"
|
|
New-Item -ItemType Directory -Force -Path $out | Out-Null
|
|
|
|
graccess object get --galaxy $galaxy --name $name --type template --json `
|
|
| Set-Content "$out\object.json"
|
|
|
|
graccess object attributes --galaxy $galaxy --name $name --type template --json `
|
|
| Set-Content "$out\attributes.json"
|
|
|
|
graccess object attributes --galaxy $galaxy --name $name --type template --configurable --json `
|
|
| Set-Content "$out\configurable-attributes.json"
|
|
|
|
graccess object extended-attributes --galaxy $galaxy --name $name --type template --json `
|
|
| Set-Content "$out\extended-attributes.json"
|
|
```
|
|
|
|
Compare before and after snapshots:
|
|
|
|
```powershell
|
|
Compare-Object `
|
|
(Get-Content '.\template-snapshots\TestMachine-before\attributes.json') `
|
|
(Get-Content '.\template-snapshots\TestMachine-after\attributes.json')
|
|
```
|
|
|
|
Also verify command summaries after each mutation. GRAccess returns `CommandResult` or `CommandResults`; failed calls should be treated as failed edits even if the CLI process exits after printing output.
|
|
|
|
## Rollback Options
|
|
|
|
Rollback depends on what changed:
|
|
|
|
| Change type | Rollback path |
|
|
|---|---|
|
|
| Unchecked-in edit | `object undo-checkout` |
|
|
| Attribute value/metadata edit | Restore previous value with another edit cycle |
|
|
| UDA or extension edit | Reverse the add/delete/rename/update operation |
|
|
| Derived test template | Delete the derived template after validation |
|
|
| Full object/package edit | Re-import the pre-edit export package with explicit confirmation |
|
|
|
|
Importing packages is production-impacting and requires exact confirmation:
|
|
|
|
```powershell
|
|
graccess galaxy import-objects --galaxy ZB --file '.\template-snapshots\TestMachine-before\TestMachine.aaPKG' --overwrite --confirm --confirm-target '.\template-snapshots\TestMachine-before\TestMachine.aaPKG'
|
|
```
|
|
|
|
## Current CLI Gaps For Full-Fidelity Editing
|
|
|
|
The current CLI can edit object properties, attribute values, locks, security classifications, buffers, UDAs, extensions, derived templates, instances, and script libraries. Full-fidelity template editing still has gaps:
|
|
|
|
| Area | Current status | Recommended next step |
|
|
|---|---|---|
|
|
| Attribute value readback | Values are not emitted by `object attributes` | Add defensive `IAttribute.Value` serialization |
|
|
| History/I/O/alarm value editing | Possible only when the setting is a known attribute and supported value type | Add typed setting commands or broader `MxValue` support |
|
|
| Object-level script bodies | Not exposed as JSON | Add `object scripts get/set` or use export/import |
|
|
| Object-reference property assignment | Raw string assignment may fail for some COM properties | Resolve named GRAccess objects before assignment |
|
|
| Validation details | `object get` does not emit all errors/warnings/status fields | Extend object detail output defensively |
|
|
|
|
Prefer implementing those gaps as read-only parse support first, then mutation support with confirmation guards.
|