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>
276 lines
11 KiB
Markdown
276 lines
11 KiB
Markdown
# Parsing Existing Templates
|
|
|
|
This guide describes a read-only workflow for inspecting an existing GRAccess template, using `TestMachine` as the example target. The same steps work for any template name.
|
|
|
|
Use this document as the top-level workflow. For deeper coverage, also read:
|
|
|
|
- `attribute-parsing.md` - all attributes, configurable attributes, extended attributes, and setting families such as history, I/O, alarms, UDAs, and extensions.
|
|
- `script-parsing.md` - script libraries, object-level script discovery, and export-based script capture.
|
|
|
|
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 --
|
|
```
|
|
|
|
Run commands from `graccess_cli`.
|
|
|
|
## Session Setup
|
|
|
|
For repeated template parsing, start a session first so commands reuse one GRAccess login:
|
|
|
|
```powershell
|
|
graccess session start --galaxy ZB --node .
|
|
```
|
|
|
|
After a session is active, logged-in commands can omit `--node`:
|
|
|
|
```powershell
|
|
graccess template list --galaxy ZB --pattern '%TestMachine%' --json
|
|
```
|
|
|
|
Without a session, include `--node .` on each command:
|
|
|
|
```powershell
|
|
graccess template list --galaxy ZB --node . --pattern '%TestMachine%' --json
|
|
```
|
|
|
|
For LLM-driven parsing, prefer the bundled machine snapshot before running narrower commands:
|
|
|
|
```powershell
|
|
graccess object snapshot --galaxy ZB --name TestMachine --type template --llm-json
|
|
```
|
|
|
|
Use the narrower `object attributes`, `object extended-attributes`, and script commands when you need to drill into a specific section or compare legacy `--json` output.
|
|
|
|
## Find The Template
|
|
|
|
Use `template list` to confirm the exact template tagname. GRAccess patterns use `%` as the wildcard.
|
|
|
|
```powershell
|
|
graccess template list --galaxy ZB --pattern '%TestMachine%' --json
|
|
```
|
|
|
|
If the template name starts with `$`, quote it with single quotes in PowerShell:
|
|
|
|
```powershell
|
|
graccess template list --galaxy ZB --pattern '%$TestMachine%' --json
|
|
```
|
|
|
|
## Read Template Identity
|
|
|
|
Use `object get` with `--type template` to fetch the core object record:
|
|
|
|
```powershell
|
|
graccess object get --galaxy ZB --name TestMachine --type template --json
|
|
```
|
|
|
|
Expected fields include:
|
|
|
|
| Field | Meaning |
|
|
|---|---|
|
|
| `Kind` | `template` for template objects |
|
|
| `Tagname` | Template tagname |
|
|
| `ContainedName` | Name inside its container |
|
|
| `HierarchicalName` | Galaxy hierarchy path when available |
|
|
| `CheckoutStatus` | Current checkout state |
|
|
|
|
For LLM-oriented parsing, prefer `object snapshot --llm-json` because it returns the same identity section plus attributes, relationships, script metadata, and unavailable-field details in one stable envelope.
|
|
|
|
## Parse Inheritance And Containment
|
|
|
|
Template inheritance and containment are separate relationships:
|
|
|
|
| Relationship | Meaning | Typical command |
|
|
| --- | --- | --- |
|
|
| Derived from | Template extends another template, such as `$TestMachine` extending `$gMachine` | `object snapshot`, `object lineage`, `object query-condition --condition derivedOrInstantiatedFrom` |
|
|
| Based on | Descendant or instance family relationship to a base template | `object query-condition --condition basedOn` |
|
|
| Contained by | Embedded template or object inside a parent template/instance | `object children`, `object query-condition --condition containedBy`; `template instantiate --create-contained` for creation |
|
|
|
|
Start with the snapshot:
|
|
|
|
```powershell
|
|
graccess object snapshot --galaxy ZB --name '$TestMachine' --type template --llm-json
|
|
graccess object lineage --galaxy ZB --name '$TestMachine' --type template --llm-json
|
|
graccess object children --galaxy ZB --name '$TestMachine' --type template --llm-json
|
|
```
|
|
|
|
Check `data.Lineage`, `data.Children`, `data.ContainedObjects`, and these fields in the returned `data.Object` object:
|
|
|
|
| Field | Meaning |
|
|
| --- | --- |
|
|
| `DerivedFrom` | Immediate parent template when the local GRAccess property is exposed |
|
|
| `BasedOn` | Base template lineage when exposed |
|
|
| `ContainedName` | Embedded name inside the parent template or instance |
|
|
| `HierarchicalName` | Full contained path when exposed |
|
|
|
|
Then run relationship queries:
|
|
|
|
```powershell
|
|
graccess object query-condition --galaxy ZB --type all --condition derivedOrInstantiatedFrom --value '$gMachine' --llm-json
|
|
graccess object query-condition --galaxy ZB --type all --condition basedOn --value '$gMachine' --llm-json
|
|
graccess object query-condition --galaxy ZB --type all --condition containedBy --value '$TestMachine' --llm-json
|
|
graccess object query-condition --galaxy ZB --type all --condition hierarchicalNameLike --value '%TestMachine%' --llm-json
|
|
```
|
|
|
|
GRAccess relationship queries can be version-sensitive. The CLI now tries typed template/instance properties first, then uses a read-only exported package fallback for snapshot, lineage, children, attribute values, and script bodies when export is available. If both direct GRAccess and package fallback are unavailable, document the unavailable entry and avoid guessing. Do not use Galaxy SQL as part of normal parsing; SQL is only a development verification/debugging oracle.
|
|
|
|
Contained embedded templates should be parsed as their own templates:
|
|
|
|
```powershell
|
|
graccess object snapshot --galaxy ZB --name '$TestMachine.DelmiaReceiver' --type template --llm-json
|
|
graccess object snapshot --galaxy ZB --name '$TestMachine.MESReceiver' --type template --llm-json
|
|
```
|
|
|
|
Contained instances should be parsed as their own instances:
|
|
|
|
```powershell
|
|
graccess object snapshot --galaxy ZB --name DelmiaReceiver_001 --type instance --llm-json
|
|
graccess object snapshot --galaxy ZB --name MESReceiver_001 --type instance --llm-json
|
|
```
|
|
|
|
When available, compare `Tagname`, `ContainedName`, and `HierarchicalName` to connect child instance tags back to parent paths such as `TestMachine_001.DelmiaReceiver`.
|
|
|
|
## Dump Attributes
|
|
|
|
Use `object attributes` to enumerate the template attributes:
|
|
|
|
```powershell
|
|
graccess object attributes --galaxy ZB --name TestMachine --type template --json
|
|
```
|
|
|
|
Use `--configurable` when you only need configurable attributes:
|
|
|
|
```powershell
|
|
graccess object attributes --galaxy ZB --name TestMachine --type template --configurable --json
|
|
```
|
|
|
|
Attribute JSON includes the stable metadata currently exposed by the CLI:
|
|
|
|
| Field | Meaning |
|
|
|---|---|
|
|
| `Name` | Attribute name |
|
|
| `DataType` | GRAccess data type |
|
|
| `Category` | Attribute category |
|
|
| `SecurityClassification` | Security classification |
|
|
| `Locked` | Lock state |
|
|
| `UpperBoundDim1` | Array upper bound when available |
|
|
| `HasBuffer` | Attribute buffer flag when available |
|
|
| `RuntimeSetHandler` | Runtime set handler flag when available |
|
|
| `ConfigSetHandler` | Config set handler flag when available |
|
|
|
|
Some COM-backed metadata is not available on every attribute. In JSON output, unavailable values are returned as `null`.
|
|
|
|
## Read One Attribute
|
|
|
|
Use `object attribute get` when you already know the attribute name and need its metadata without dumping the full collection:
|
|
|
|
```powershell
|
|
graccess object attribute get --galaxy ZB --name TestMachine --type template --attribute Description --json
|
|
```
|
|
|
|
This command is read-only and does not require `--confirm`.
|
|
|
|
## Dump Extended Attributes
|
|
|
|
Use `object extended-attributes` to call GRAccess `GetExtendedAttributes` for the template:
|
|
|
|
```powershell
|
|
graccess object extended-attributes --galaxy ZB --name TestMachine --type template --json
|
|
```
|
|
|
|
You can scope the request with an attribute name and hierarchy level:
|
|
|
|
```powershell
|
|
graccess object extended-attributes --galaxy ZB --name TestMachine --type template --attribute Description --level 0 --json
|
|
```
|
|
|
|
The output uses the same attribute metadata shape as `object attributes`.
|
|
|
|
For parsing all attribute settings, including properties, history settings, I/O settings, alarm settings, UDAs, and extensions, use the expanded workflow in `attribute-parsing.md`.
|
|
|
|
## Capture Scripts
|
|
|
|
Template scripts may appear as script-related attributes, extension attributes, exported object package content, or script libraries. Use `script-parsing.md` when a parse needs script bodies, declarations, triggers, or script-library files.
|
|
|
|
Minimum script-related capture for `TestMachine`:
|
|
|
|
```powershell
|
|
graccess script-library list --galaxy ZB --json
|
|
graccess object attributes --galaxy ZB --name TestMachine --type template --json
|
|
graccess object extended-attributes --galaxy ZB --name TestMachine --type template --json
|
|
```
|
|
|
|
For complete script content, export the template object:
|
|
|
|
```powershell
|
|
$pkg = '.\template-snapshots\TestMachine\TestMachine.aaPKG'
|
|
graccess objects export --galaxy ZB --type template --name TestMachine --output $pkg --confirm --confirm-target $pkg
|
|
```
|
|
|
|
## Find Related Objects
|
|
|
|
Use `object query-condition` to find objects related to the template.
|
|
|
|
First-level derived templates or instantiated instances:
|
|
|
|
```powershell
|
|
graccess object query-condition --galaxy ZB --type all --condition derivedOrInstantiatedFrom --value TestMachine --json
|
|
```
|
|
|
|
All descendants based on the same base template:
|
|
|
|
```powershell
|
|
graccess object query-condition --galaxy ZB --type all --condition basedOn --value TestMachine --json
|
|
```
|
|
|
|
Objects contained by the template:
|
|
|
|
```powershell
|
|
graccess object query-condition --galaxy ZB --type all --condition containedBy --value TestMachine --json
|
|
```
|
|
|
|
Useful `EConditionType` values for parsing template relationships are documented in `graccess_documentation.md` under `EConditionType`. The most common values for template parsing are `namedLike`, `NameEquals`, `derivedOrInstantiatedFrom`, `basedOn`, `containedBy`, and `hierarchicalNameLike`.
|
|
|
|
## Save A Local Parse Snapshot
|
|
|
|
PowerShell can capture JSON output into files for comparison or downstream processing:
|
|
|
|
```powershell
|
|
$name = 'TestMachine'
|
|
$out = '.\template-snapshots'
|
|
New-Item -ItemType Directory -Force -Path $out | Out-Null
|
|
|
|
graccess object get --galaxy ZB --name $name --type template --json `
|
|
| Set-Content "$out\$name.object.json"
|
|
|
|
graccess object attributes --galaxy ZB --name $name --type template --json `
|
|
| Set-Content "$out\$name.attributes.json"
|
|
|
|
graccess object attributes --galaxy ZB --name $name --type template --configurable --json `
|
|
| Set-Content "$out\$name.configurable-attributes.json"
|
|
|
|
graccess object extended-attributes --galaxy ZB --name $name --type template --json `
|
|
| Set-Content "$out\$name.extended-attributes.json"
|
|
|
|
graccess script-library list --galaxy ZB --json `
|
|
| Set-Content "$out\script-libraries.json"
|
|
|
|
graccess object query-condition --galaxy ZB --type all --condition derivedOrInstantiatedFrom --value $name --json `
|
|
| Set-Content "$out\$name.children.json"
|
|
|
|
graccess object query-condition --galaxy ZB --type all --condition basedOn --value $name --json `
|
|
| Set-Content "$out\$name.descendants.json"
|
|
```
|
|
|
|
To inspect the parsed JSON in PowerShell:
|
|
|
|
```powershell
|
|
$attrs = Get-Content '.\template-snapshots\TestMachine.attributes.json' -Raw | ConvertFrom-Json
|
|
$attrs | Sort-Object Name | Select-Object Name, DataType, Category, Locked
|
|
```
|
|
|
|
## Safety Notes
|
|
|
|
The commands in this guide are read-only. Do not use `object set`, `object attribute set`, `object uda`, `object extension`, `template derive`, `template instantiate`, or delete/deploy commands while parsing unless you intentionally want to mutate the galaxy and pass the required `--confirm` and `--confirm-target` flags.
|