Initial commit: Wonderware / System Platform tools and reference
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>
This commit is contained in:
Joseph Doherty
@@ -0,0 +1,17 @@
|
||||
# GRAccess CLI Documentation
|
||||
|
||||
This folder stores user-facing and implementation reference documentation for `graccess_cli`.
|
||||
|
||||
- `usage.md` - CLI commands, options, session mode, IPC protocol, and expanded command surface. Update this whenever user-facing commands change.
|
||||
- `llm-integration.md` - implemented LLM-facing operating contract, stable envelope, safety rules, validation, batch plans, and IDE intent wrappers.
|
||||
- `adding-features.md` - contributor checklist for adding commands, dispatcher handlers, LLM output, validation, tests, and documentation.
|
||||
- `zb-galaxy.md` - read-only documentation captured from the live `ZB` galaxy with `graccess_cli`.
|
||||
- `zb-testmachine.md` - deep read-only documentation of the `ZB` `$TestMachine` template family and instances.
|
||||
- `template-parsing.md` - read-only workflow for inspecting existing templates such as `TestMachine`.
|
||||
- `attribute-parsing.md` - detailed workflow for parsing all template attributes and setting families.
|
||||
- `script-parsing.md` - workflow for parsing script libraries and object-level scripts.
|
||||
- `template-editing.md` - end-to-end workflow for safely editing existing templates.
|
||||
- `template-instance-editing.md` - workflow for creating and editing template instances, areas, engine assignments, and I/O settings.
|
||||
- `attribute-editing.md` - detailed workflow for editing template attributes, UDAs, extensions, and setting families.
|
||||
- `script-editing.md` - workflow for editing script libraries and script-bearing template content.
|
||||
- `clifx_reference.md` - local CliFx framework reference.
|
||||
@@ -0,0 +1,192 @@
|
||||
# Adding GRAccess CLI Features
|
||||
|
||||
Use this checklist when adding a new `graccess_cli` command, option, output field, dispatcher operation, or LLM-facing workflow. The goal is to keep human CLI behavior, script compatibility, session routing, and LLM automation aligned.
|
||||
|
||||
## First Read
|
||||
|
||||
Before editing code, read the relevant source material:
|
||||
|
||||
- `graccess_operations.md` for the operation family and page references.
|
||||
- `graccess_documentation.md` for exact GRAccess signatures, enum names, return types, and object model constraints.
|
||||
- `docs/usage.md` for the current public CLI contract.
|
||||
- `docs/llm-integration.md` for machine-facing output, validation, batch, and confirmation rules.
|
||||
- The domain docs that match the feature: parsing, editing, scripts, attributes, or template instances.
|
||||
|
||||
Do not infer COM behavior from names alone. GRAccess methods often return `CommandResult` or `CommandResults` and may expose properties that throw when backing storage is unavailable.
|
||||
|
||||
## Decide The Command Shape
|
||||
|
||||
Choose the smallest command that maps clearly to the GRAccess operation.
|
||||
|
||||
- Use established CliFx patterns: command classes implement `ICommand` and use `[Command]`, `[CommandParameter]`, and `[CommandOption]`.
|
||||
- Keep galaxy-bound commands routable through `CommandRouter`.
|
||||
- Keep pre-login galaxy operations one-shot when they cannot use a galaxy-specific session.
|
||||
- Prefer explicit subcommands over overloaded string modes.
|
||||
- Preserve existing command names and existing `--json` shapes.
|
||||
- Add `--llm-json` for machine-stable output when the command is useful to automation.
|
||||
- Add `--dry-run` to mutating routed commands for validation without invoking mutating COM calls.
|
||||
|
||||
For mutating operations, choose the safety rule before implementation:
|
||||
|
||||
- All mutations require `--confirm`.
|
||||
- Destructive, deployment, import/export, restore, migrate, GRLoad, and object configuration changes require `--confirm-target <exact target>`.
|
||||
- Batch plans must include per-step `confirm: true` and exact `confirm-target`; do not add global mutation confirmation.
|
||||
|
||||
## Register Capabilities
|
||||
|
||||
Every public command intended for automation must be represented in `Infrastructure/CommandCapabilityRegistry.cs`.
|
||||
|
||||
Add or update:
|
||||
|
||||
- Command name.
|
||||
- Required and optional args.
|
||||
- Whether it mutates state.
|
||||
- Whether it supports session routing.
|
||||
- Whether it requires `--confirm`.
|
||||
- Whether it requires `--confirm-target`, and which target rule applies.
|
||||
- Output modes, including `text`, `json`, and `llm-json` where supported.
|
||||
- Schema name for the request or response family.
|
||||
|
||||
The registry is the source for `graccess capabilities`, `graccess validate`, batch validation, and tests. Do not scrape docs or help output to discover commands.
|
||||
|
||||
## Add The CliFx Wrapper
|
||||
|
||||
Put thin command wrappers in the existing command area that matches the feature:
|
||||
|
||||
- `Commands/GRAccessSurfaceCommands.cs` for most expanded GRAccess operation surface commands.
|
||||
- `Commands/Objects/*` for established object list/query commands.
|
||||
- `Commands/Galaxy/*` for galaxy commands.
|
||||
- `Commands/LlmCommands.cs` for capabilities, validate, and batch behavior.
|
||||
|
||||
Wrapper responsibilities should stay narrow:
|
||||
|
||||
- Parse CLI args.
|
||||
- Build a structured `Dictionary<string, object>` request.
|
||||
- Pass the request to `CommandRouter` for galaxy-bound work.
|
||||
- Print text, legacy JSON, or LLM JSON exactly once.
|
||||
|
||||
Do not put GRAccess COM logic in command wrappers unless the operation is explicitly one-shot and cannot be session-routed.
|
||||
|
||||
## Route Through The Dispatcher
|
||||
|
||||
Galaxy-bound behavior belongs in `GRAccess/GRAccessCommandDispatcher.cs`.
|
||||
|
||||
When adding a handler:
|
||||
|
||||
- Dispatch by command family and subcommand.
|
||||
- Keep daemon and one-shot behavior identical by using the same dispatcher path.
|
||||
- Keep all daemon COM access on `StaComThread`.
|
||||
- Check GRAccess `CommandResult.Successful` or every result in `CommandResults`.
|
||||
- For object mutations, follow `CheckOut()` -> modify -> `Save()` -> `CheckIn(comment)`.
|
||||
- Use defensive reads for optional COM-backed properties.
|
||||
- Represent unreadable fields as structured unavailable data instead of throwing when a partial result is useful.
|
||||
|
||||
For object-reference assignment, prefer resolving named GRAccess objects first and only fall back to string assignment when the API allows it.
|
||||
|
||||
## Output Rules
|
||||
|
||||
Legacy behavior is part of the contract.
|
||||
|
||||
- Do not change existing `--json` shapes for existing commands.
|
||||
- `--llm-json` must use the stable envelope:
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"command": "object get",
|
||||
"galaxy": "ZB",
|
||||
"target": "TestMachine",
|
||||
"data": {},
|
||||
"commandResult": null,
|
||||
"warnings": [],
|
||||
"unavailable": []
|
||||
}
|
||||
```
|
||||
|
||||
- Failure envelopes must include `success: false`, `error`, `exitCode`, and any useful GRAccess command result details.
|
||||
- Normal log lines must not pollute `--llm-json` stdout.
|
||||
- Include unavailable fields in `unavailable` when GRAccess lacks direct support or the local COM layer throws.
|
||||
- Include `CommandResult` / `CommandResults` details for mutations.
|
||||
|
||||
## Validation And Dry Run
|
||||
|
||||
Validation should catch request-shape and safety issues before COM mutation.
|
||||
|
||||
- Add required args and confirmation rules to `CommandCapabilityRegistry`.
|
||||
- Ensure `graccess validate --request plan.json --llm-json` catches missing args, unknown commands, and mismatched confirmation targets.
|
||||
- Ensure `graccess batch --mode validate --llm-json` validates every step.
|
||||
- Ensure `--dry-run` validates args, routing, and confirmation without calling mutating GRAccess methods.
|
||||
|
||||
If a true GRAccess dry-run is not available, document that dry-run is input and routing validation only.
|
||||
|
||||
## Tests
|
||||
|
||||
Add focused tests for the changed behavior.
|
||||
|
||||
Minimum expected coverage:
|
||||
|
||||
- Capability registry entry for the new command.
|
||||
- Command parsing for the public CLI shape.
|
||||
- Dispatcher request mapping from CliFx wrapper to command/subcommand/args.
|
||||
- Confirmation guard behavior for normal, dry-run, and batch paths when the command mutates.
|
||||
- Legacy `--json` compatibility if an existing command changed.
|
||||
- `--llm-json` success and failure envelope shape when LLM output is supported.
|
||||
- Structured IPC round-trip if the command uses arrays, condition lists, booleans, enums, or object batches.
|
||||
- Fake or mocked handler tests for session route and one-shot route equivalence when practical.
|
||||
|
||||
Live validation against `ZB` should be read-only unless the test creates an explicitly named disposable object and removes it afterward. Never run wildcard bulk mutation live.
|
||||
|
||||
## Documentation Updates
|
||||
|
||||
Update docs in the same change as the feature.
|
||||
|
||||
Required updates:
|
||||
|
||||
- `docs/usage.md` for every user-facing command, option, output mode, and example.
|
||||
- `docs/llm-integration.md` for every LLM-facing command, envelope field, batch behavior, validation behavior, or safety rule.
|
||||
- `docs/README.md` if a new documentation page is added.
|
||||
- `AGENTS.md` and `CLAUDE.md` when agent-critical workflows, constraints, or references change.
|
||||
|
||||
Domain-specific updates:
|
||||
|
||||
- Parsing commands: update `template-parsing.md`, `attribute-parsing.md`, or `script-parsing.md`.
|
||||
- Editing commands: update `template-editing.md`, `template-instance-editing.md`, `attribute-editing.md`, or `script-editing.md`.
|
||||
- IDE intent wrappers: update `template-instance-editing.md` and `llm-integration.md`.
|
||||
- Safety changes: update all docs that include mutation examples.
|
||||
|
||||
Documentation should include:
|
||||
|
||||
- Command syntax.
|
||||
- Required flags.
|
||||
- Confirmation requirements.
|
||||
- Session behavior.
|
||||
- `--llm-json` example when useful.
|
||||
- Any known GRAccess limitation or unavailable field behavior.
|
||||
|
||||
## Implementation Checklist
|
||||
|
||||
Use this order for most features:
|
||||
|
||||
1. Find the GRAccess API operation and confirm signatures.
|
||||
2. Design the CLI command and safety rule.
|
||||
3. Add or update capability registry metadata.
|
||||
4. Add the CliFx wrapper.
|
||||
5. Add the dispatcher handler.
|
||||
6. Preserve legacy output and add `--llm-json` if machine-facing.
|
||||
7. Add validation, dry-run, and batch support where applicable.
|
||||
8. Add tests.
|
||||
9. Update docs.
|
||||
10. Run build and tests.
|
||||
11. Run read-only smoke validation against `ZB` when the feature can be safely verified.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- Loading GRAccess from x64 or non-STA code.
|
||||
- Letting `GRAccessApp` go out of scope while derived objects are still in use.
|
||||
- Changing legacy `--json` output while adding `--llm-json`.
|
||||
- Returning success for unsupported COM behavior instead of structured unavailable details.
|
||||
- Adding a command wrapper but forgetting `CommandCapabilityRegistry`.
|
||||
- Adding a dispatcher handler that only works in one-shot mode.
|
||||
- Running mutating live validation against real objects or wildcard selections.
|
||||
- Assuming GRAccess collections are zero-based.
|
||||
- Forgetting to update `docs/usage.md`.
|
||||
@@ -0,0 +1,270 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,249 @@
|
||||
# Parsing Template Attributes
|
||||
|
||||
This guide describes how to parse attributes for an existing GRAccess template such as `TestMachine`, including the settings families normally needed for template analysis: object properties, attribute metadata, history settings, I/O settings, alarm settings, and extension/UDA settings.
|
||||
|
||||
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 workflows, start with the stable snapshot envelope:
|
||||
|
||||
```powershell
|
||||
graccess object snapshot --galaxy ZB --name TestMachine --type template --llm-json
|
||||
```
|
||||
|
||||
Then use `object attribute value get --llm-json` for individual scalar value readback. The value command tries direct `IAttribute.Value` first and then the read-only package fallback.
|
||||
|
||||
## Attribute Sources
|
||||
|
||||
Use all three read paths when building a complete parse:
|
||||
|
||||
| Source | Command | Purpose |
|
||||
|---|---|---|
|
||||
| Object identity | `object get` | Template tagname, contained name, hierarchy, checkout status |
|
||||
| All attributes | `object attributes` | Every attribute visible through `IgObject.Attributes` |
|
||||
| Configurable attributes | `object attributes --configurable` | Attributes visible through `IgObject.ConfigurableAttributes` |
|
||||
| Extended attributes | `object extended-attributes` | Inherited or hierarchy-expanded attributes from `GetExtendedAttributes` |
|
||||
| One attribute | `object attribute get` | Metadata for a known attribute |
|
||||
| One attribute value | `object attribute value get` | Scalar value readback through direct GRAccess or package fallback where supported |
|
||||
|
||||
Base commands:
|
||||
|
||||
```powershell
|
||||
graccess object get --galaxy ZB --name TestMachine --type template --json
|
||||
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
|
||||
```
|
||||
|
||||
## Current CLI Coverage
|
||||
|
||||
The current CLI exposes the stable `IAttribute` metadata listed below.
|
||||
|
||||
| JSON field | GRAccess API member | Notes |
|
||||
|---|---|---|
|
||||
| `Name` | `IAttribute.Name` | Attribute name |
|
||||
| `DataType` | `IAttribute.DataType` | `MxDataType` value |
|
||||
| `Category` | `IAttribute.AttributeCategory` | Attribute category |
|
||||
| `SecurityClassification` | `IAttribute.SecurityClassification` | Security classification |
|
||||
| `Locked` | `IAttribute.Locked` | Lock state |
|
||||
| `UpperBoundDim1` | `IAttribute.UpperBoundDim1` | First array dimension upper bound |
|
||||
| `HasBuffer` | `IAttribute.HasBuffer` | Attribute buffer flag |
|
||||
| `RuntimeSetHandler` | `IAttribute.RtSethandler` | Runtime set handler flag |
|
||||
| `ConfigSetHandler` | `IAttribute.CfgSethandler` | Configuration set handler flag |
|
||||
|
||||
The GRAccess API also exposes `IAttribute.Value`. The CLI serializes scalar values when the local COM object exposes a supported accessor, and falls back to a temporary exported package when direct readback is unavailable. Because many history, I/O, alarm, and script-related settings are stored as attribute values, strict value-level parsing should use these paths:
|
||||
|
||||
| Need | Best current path |
|
||||
|---|---|
|
||||
| Inventory every setting name and metadata | `object attributes`, `--configurable`, and `object extended-attributes` |
|
||||
| Read a single setting metadata record | `object attribute get` |
|
||||
| Read one scalar value | `object attribute value get --llm-json` |
|
||||
| Preserve full vendor configuration, including values and scripts | `object snapshot --llm-json` package fallback, `objects export`, or `galaxy export-all` |
|
||||
| Arrays or complex values | Treat as unavailable unless the snapshot/package parser emits a safe scalar representation |
|
||||
|
||||
Normal CLI parsing must not query the Galaxy SQL database for attribute values. SQL can be used only in development verification scripts to compare GRAccess/package output against repository facts.
|
||||
|
||||
## Parse All Attributes
|
||||
|
||||
Capture all attribute lists before classifying them:
|
||||
|
||||
```powershell
|
||||
$name = 'TestMachine'
|
||||
$out = '.\template-snapshots'
|
||||
New-Item -ItemType Directory -Force -Path $out | Out-Null
|
||||
|
||||
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"
|
||||
```
|
||||
|
||||
Load the snapshot in PowerShell:
|
||||
|
||||
```powershell
|
||||
$attrs = Get-Content '.\template-snapshots\TestMachine.attributes.json' -Raw | ConvertFrom-Json
|
||||
$configurable = Get-Content '.\template-snapshots\TestMachine.configurable-attributes.json' -Raw | ConvertFrom-Json
|
||||
$extended = Get-Content '.\template-snapshots\TestMachine.extended-attributes.json' -Raw | ConvertFrom-Json
|
||||
```
|
||||
|
||||
Merge and de-duplicate by attribute name:
|
||||
|
||||
```powershell
|
||||
$all = @($attrs) + @($configurable) + @($extended)
|
||||
$byName = $all | Sort-Object Name -Unique
|
||||
$byName | Select-Object Name, DataType, Category, Locked, HasBuffer
|
||||
```
|
||||
|
||||
## Parse Object Properties
|
||||
|
||||
Object-level properties are not the same as attributes. The current `object get` output gives identity and checkout information:
|
||||
|
||||
```powershell
|
||||
graccess object get --galaxy ZB --name TestMachine --type template --json
|
||||
```
|
||||
|
||||
`graccess_operations.md` lists additional GRAccess object properties that exist on `ITemplate` and `IInstance`, including `DerivedFrom`, `BasedOn`, `Category`, `CategoryGUID`, `Container`, `Area`, `Host`, `Toolset`, `ConfigVersion`, `CheckedOutBy`, `EditStatus`, `ValidationStatus`, `Errors`, and `Warnings`.
|
||||
|
||||
The current CLI does not emit every one of those properties in `object get`. If a parse requires all object properties, extend `GRAccessCommandDispatcher.ObjectDetails(...)` to read them defensively with the same `Try(...)` pattern used for current COM-backed fields.
|
||||
|
||||
## Parse History Settings
|
||||
|
||||
History settings are commonly represented as attributes or extended attributes. To parse them:
|
||||
|
||||
1. Capture all attributes and extended attributes.
|
||||
2. Find setting names related to history or historian configuration.
|
||||
3. Preserve metadata for each matching attribute.
|
||||
4. Use object export or a future value-emitting CLI command when actual setting values are required.
|
||||
|
||||
PowerShell classification:
|
||||
|
||||
```powershell
|
||||
$history = $byName | Where-Object {
|
||||
$_.Name -match '(?i)hist|history|historian|storage|trend'
|
||||
}
|
||||
|
||||
$history | Sort-Object Name | Select-Object Name, DataType, Category, Locked, HasBuffer
|
||||
```
|
||||
|
||||
This is intentionally name-driven because exact attribute names vary by template type, System Platform version, primitive, and extension package.
|
||||
|
||||
## Parse I/O Settings
|
||||
|
||||
I/O settings can appear as object-level assignment properties, attributes, extension attributes, or exported package content. Parse them in this order:
|
||||
|
||||
1. `object get` for identity and hierarchy.
|
||||
2. `object attributes` and `object extended-attributes` for setting names and metadata.
|
||||
3. Query relationships such as host, containment, and area when relevant.
|
||||
4. Use export for full value-level source/destination details.
|
||||
|
||||
PowerShell classification:
|
||||
|
||||
```powershell
|
||||
$io = $byName | Where-Object {
|
||||
$_.Name -match '(?i)\bio\b|input|output|source|destination|scan|topic|device|address|reference'
|
||||
}
|
||||
|
||||
$io | Sort-Object Name | Select-Object Name, DataType, Category, Locked, RuntimeSetHandler, ConfigSetHandler
|
||||
```
|
||||
|
||||
Relationship queries that often help with I/O context:
|
||||
|
||||
```powershell
|
||||
graccess object query-condition --galaxy ZB --type all --condition containedBy --value TestMachine --json
|
||||
graccess object query-condition --galaxy ZB --type all --condition assignedTo --value TestMachine --json
|
||||
graccess object query-condition --galaxy ZB --type all --condition hostEngineIs --value TestMachine --json
|
||||
```
|
||||
|
||||
## Parse Alarm Settings
|
||||
|
||||
Alarm settings are usually represented as attributes and extension attributes. Capture all attribute sources, then classify by alarm-related names:
|
||||
|
||||
```powershell
|
||||
$alarm = $byName | Where-Object {
|
||||
$_.Name -match '(?i)alarm|alert|limit|priority|severity|deadband|deviation|rate|roc|hihi|lolo|(^|[._])hi($|[._])|(^|[._])lo($|[._])|ack'
|
||||
}
|
||||
|
||||
$alarm | Sort-Object Name | Select-Object Name, DataType, Category, SecurityClassification, Locked
|
||||
```
|
||||
|
||||
For value-level alarm settings, use `objects export` until the CLI emits `IAttribute.Value`.
|
||||
|
||||
## Parse UDAs And Extensions
|
||||
|
||||
User-defined attributes are included in the attribute collections. Extension primitives normally show up through extended attributes, object export, or extension-specific attributes.
|
||||
|
||||
Recommended read-only capture:
|
||||
|
||||
```powershell
|
||||
graccess object attributes --galaxy ZB --name TestMachine --type template --json
|
||||
graccess object extended-attributes --galaxy ZB --name TestMachine --type template --json
|
||||
```
|
||||
|
||||
The CLI currently has mutation commands for UDA and extension management, but it does not have a dedicated read-only `object uda list` or `object extension list` command. For complete extension parsing, prefer export or add dedicated list commands that call the GRAccess object/extension APIs if available in the local COM assembly.
|
||||
|
||||
## Full Attribute Snapshot Script
|
||||
|
||||
This script creates a structured local parse folder and classifies likely setting families:
|
||||
|
||||
```powershell
|
||||
$galaxy = 'ZB'
|
||||
$name = 'TestMachine'
|
||||
$type = 'template'
|
||||
$out = ".\template-snapshots\$name"
|
||||
New-Item -ItemType Directory -Force -Path $out | Out-Null
|
||||
|
||||
graccess object get --galaxy $galaxy --name $name --type $type --json `
|
||||
| Set-Content "$out\object.json"
|
||||
|
||||
graccess object attributes --galaxy $galaxy --name $name --type $type --json `
|
||||
| Set-Content "$out\attributes.json"
|
||||
|
||||
graccess object attributes --galaxy $galaxy --name $name --type $type --configurable --json `
|
||||
| Set-Content "$out\configurable-attributes.json"
|
||||
|
||||
graccess object extended-attributes --galaxy $galaxy --name $name --type $type --json `
|
||||
| Set-Content "$out\extended-attributes.json"
|
||||
|
||||
$all = @(
|
||||
Get-Content "$out\attributes.json" -Raw | ConvertFrom-Json
|
||||
) + @(
|
||||
Get-Content "$out\configurable-attributes.json" -Raw | ConvertFrom-Json
|
||||
) + @(
|
||||
Get-Content "$out\extended-attributes.json" -Raw | ConvertFrom-Json
|
||||
)
|
||||
|
||||
$byName = $all | Sort-Object Name -Unique
|
||||
$byName | ConvertTo-Json -Depth 5 | Set-Content "$out\all-attributes.unique.json"
|
||||
|
||||
$groups = [ordered]@{
|
||||
history = @($byName | Where-Object { $_.Name -match '(?i)hist|history|historian|storage|trend' })
|
||||
io = @($byName | Where-Object { $_.Name -match '(?i)\bio\b|input|output|source|destination|scan|topic|device|address|reference' })
|
||||
alarm = @($byName | Where-Object { $_.Name -match '(?i)alarm|alert|limit|priority|severity|deadband|deviation|rate|roc|hihi|lolo|(^|[._])hi($|[._])|(^|[._])lo($|[._])|ack' })
|
||||
script = @($byName | Where-Object { $_.Name -match '(?i)script|execute|trigger|expression|declaration|startup|shutdown' })
|
||||
}
|
||||
|
||||
$groups | ConvertTo-Json -Depth 8 | Set-Content "$out\attribute-groups.json"
|
||||
```
|
||||
|
||||
## CLI Gap For Complete Attribute Values
|
||||
|
||||
To make `graccess_cli` parse all attribute settings without relying on export files, add a read-only command or extend `object attributes` to include safe value serialization:
|
||||
|
||||
| Proposed field | Source |
|
||||
|---|---|
|
||||
| `Value` | `IAttribute.Value` converted from `IMxValue` |
|
||||
| `IsArray` | Derived from bounds and value shape |
|
||||
| `Dimensions` | `UpperBoundDim1` and any additional dimensions exposed by local API |
|
||||
| `CommandResult` | `IAttribute.CommandResult` after value reads where relevant |
|
||||
| `UnavailableReason` | Exception message when a COM-backed field cannot be read |
|
||||
|
||||
Keep value reads defensive. Some attributes may throw because storage is unavailable, the value is runtime-only, the datatype is not serializable, or the current login cannot read the field.
|
||||
@@ -0,0 +1,245 @@
|
||||
# CliFx Reference (v2.3.6)
|
||||
|
||||
Local reference for the CliFx CLI framework. Source: https://github.com/Tyrrrz/CliFx
|
||||
|
||||
## Setup
|
||||
|
||||
```csharp
|
||||
using CliFx;
|
||||
|
||||
public static class Program
|
||||
{
|
||||
public static async Task<int> Main() =>
|
||||
await new CliApplicationBuilder()
|
||||
.AddCommandsFromThisAssembly()
|
||||
.Build()
|
||||
.RunAsync();
|
||||
}
|
||||
```
|
||||
|
||||
**Important:** `Main()` must return the integer exit code from `RunAsync()`.
|
||||
|
||||
`RunAsync()` resolves args from `Environment.GetCommandLineArgs()` and env vars from `Environment.GetEnvironmentVariables()`. You can also provide them manually via overloads.
|
||||
|
||||
## Defining Commands
|
||||
|
||||
Commands implement `ICommand` and are decorated with `[Command]`:
|
||||
|
||||
```csharp
|
||||
using CliFx;
|
||||
using CliFx.Attributes;
|
||||
|
||||
[Command(Description = "Calculates the logarithm of a value.")]
|
||||
public class LogCommand : ICommand
|
||||
{
|
||||
[CommandParameter(0, Description = "Value whose logarithm is to be found.")]
|
||||
public required double Value { get; init; }
|
||||
|
||||
[CommandOption("base", 'b', Description = "Logarithm base.")]
|
||||
public double Base { get; init; } = 10;
|
||||
|
||||
public ValueTask ExecuteAsync(IConsole console)
|
||||
{
|
||||
var result = Math.Log(Value, Base);
|
||||
console.Output.WriteLine(result);
|
||||
return default;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Use `IConsole` (not `System.Console`) for all console I/O — this enables testability.
|
||||
|
||||
## Parameters vs Options
|
||||
|
||||
| Aspect | `[CommandParameter]` | `[CommandOption]` |
|
||||
|---|---|---|
|
||||
| Binding | By position order | By name (`--foo`) or short name (`-f`) |
|
||||
| Required by default | Yes | No |
|
||||
| Make optional | Omit `required` (last param only) | Omit `required` |
|
||||
| Make required | Use `required` keyword | Use `required` keyword |
|
||||
| Non-scalar (collections) | Only last parameter | Any option |
|
||||
| Env var fallback | No | Yes (`EnvironmentVariable = "ENV_FOO"`) |
|
||||
|
||||
```csharp
|
||||
// Required option
|
||||
[CommandOption("foo")]
|
||||
public required string Foo { get; init; }
|
||||
|
||||
// Optional parameter (must be last)
|
||||
[CommandParameter(0)]
|
||||
public string? OptionalParam { get; init; }
|
||||
|
||||
// Option with env var fallback
|
||||
[CommandOption("foo", EnvironmentVariable = "ENV_FOO")]
|
||||
public required string FooWithFallback { get; init; }
|
||||
|
||||
// Non-scalar option
|
||||
[CommandOption("items")]
|
||||
public required IReadOnlyList<string> Items { get; init; }
|
||||
```
|
||||
|
||||
## Argument Syntax (POSIX-style)
|
||||
|
||||
```
|
||||
myapp [...directives] [command] [...parameters] [...options]
|
||||
```
|
||||
|
||||
- `--foo bar` → option "foo" = "bar"
|
||||
- `-f bar` → option 'f' = "bar"
|
||||
- `--switch` → option "switch" (no value / boolean)
|
||||
- `-abc` → options 'a', 'b', 'c' (no value)
|
||||
- `-i file1.txt file2.txt` → option 'i' = ["file1.txt", "file2.txt"]
|
||||
- `-i file1.txt -i file2.txt` → same as above
|
||||
|
||||
## Value Conversion
|
||||
|
||||
Supports out of the box:
|
||||
- **Primitives**: `int`, `bool`, `double`, `ulong`, `char`, etc.
|
||||
- **Date/time**: `DateTime`, `DateTimeOffset`, `TimeSpan`
|
||||
- **Enums**: by name or numeric value
|
||||
- **String-initializable**: types with `ctor(string)` or static `Parse(string)` — e.g. `FileInfo`, `Guid`, `BigInteger`
|
||||
- **Nullable** versions of all above
|
||||
- **Collections**: `T[]`, `IReadOnlyList<T>`, `List<T>`, `HashSet<T>`, etc.
|
||||
|
||||
### Custom Converter
|
||||
|
||||
```csharp
|
||||
public class VectorConverter : BindingConverter<Vector2>
|
||||
{
|
||||
public override Vector2 Convert(string? rawValue)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(rawValue))
|
||||
return default;
|
||||
|
||||
var components = rawValue.Split('x', 'X', ';');
|
||||
var x = int.Parse(components[0], CultureInfo.InvariantCulture);
|
||||
var y = int.Parse(components[1], CultureInfo.InvariantCulture);
|
||||
|
||||
return new Vector2(x, y);
|
||||
}
|
||||
}
|
||||
|
||||
[CommandParameter(0, Converter = typeof(VectorConverter))]
|
||||
public required Vector2 Point { get; init; }
|
||||
```
|
||||
|
||||
## Multiple / Nested Commands
|
||||
|
||||
Give each command a unique name. Common name segments create hierarchy:
|
||||
|
||||
```csharp
|
||||
[Command] // Default (unnamed) command
|
||||
public class DefaultCommand : ICommand { ... }
|
||||
|
||||
[Command("cmd1")] // Child of default
|
||||
public class FirstCommand : ICommand { ... }
|
||||
|
||||
[Command("cmd1 sub")] // Child of cmd1
|
||||
public class SubCommand : ICommand { ... }
|
||||
```
|
||||
|
||||
Usage: `myapp cmd1 sub arg1 --opt value`
|
||||
|
||||
Default command is optional. If absent, running without a command shows root help text.
|
||||
|
||||
## Error Reporting
|
||||
|
||||
Use `CommandException` to report errors with specific exit codes:
|
||||
|
||||
```csharp
|
||||
throw new CommandException("Division by zero is not supported.", 133);
|
||||
```
|
||||
|
||||
Exit codes should be 1–255 (8-bit unsigned) to avoid overflow on Unix.
|
||||
|
||||
## Graceful Cancellation
|
||||
|
||||
```csharp
|
||||
public async ValueTask ExecuteAsync(IConsole console)
|
||||
{
|
||||
var cancellation = console.RegisterCancellationHandler();
|
||||
await DoSomethingAsync(cancellation);
|
||||
}
|
||||
```
|
||||
|
||||
First interrupt signal triggers the token. Second interrupt force-kills.
|
||||
|
||||
## Dependency Injection
|
||||
|
||||
Use `UseTypeActivator(...)` with `Microsoft.Extensions.DependencyInjection`:
|
||||
|
||||
```csharp
|
||||
await new CliApplicationBuilder()
|
||||
.AddCommandsFromThisAssembly()
|
||||
.UseTypeActivator(commandTypes =>
|
||||
{
|
||||
var services = new ServiceCollection();
|
||||
services.AddSingleton<MyService>();
|
||||
foreach (var commandType in commandTypes)
|
||||
services.AddTransient(commandType);
|
||||
return services.BuildServiceProvider();
|
||||
})
|
||||
.Build()
|
||||
.RunAsync();
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
Use `FakeInMemoryConsole` to test commands in isolation:
|
||||
|
||||
### Command-level test
|
||||
|
||||
```csharp
|
||||
using var console = new FakeInMemoryConsole();
|
||||
|
||||
var command = new ConcatCommand { Left = "foo", Right = "bar" };
|
||||
await command.ExecuteAsync(console);
|
||||
|
||||
var stdOut = console.ReadOutputString();
|
||||
Assert.Equal("foo bar", stdOut);
|
||||
```
|
||||
|
||||
### Application-level test
|
||||
|
||||
```csharp
|
||||
using var console = new FakeInMemoryConsole();
|
||||
|
||||
var app = new CliApplicationBuilder()
|
||||
.AddCommand<ConcatCommand>()
|
||||
.UseConsole(console)
|
||||
.Build();
|
||||
|
||||
var args = new[] { "--left", "foo", "--right", "bar" };
|
||||
var envVars = new Dictionary<string, string>();
|
||||
|
||||
await app.RunAsync(args, envVars);
|
||||
|
||||
var stdOut = console.ReadOutputString();
|
||||
Assert.Equal("foo bar", stdOut);
|
||||
```
|
||||
|
||||
## Debug & Preview Directives
|
||||
|
||||
```bash
|
||||
# Suspend until debugger attaches
|
||||
myapp [debug] cmd -o
|
||||
|
||||
# Print parsed args without executing
|
||||
myapp [preview] cmd arg1 -o foo
|
||||
```
|
||||
|
||||
Disable in production:
|
||||
|
||||
```csharp
|
||||
new CliApplicationBuilder()
|
||||
.AllowDebugMode(false)
|
||||
.AllowPreviewMode(false)
|
||||
.Build();
|
||||
```
|
||||
|
||||
## .NET Framework 4.8 Notes
|
||||
|
||||
- CliFx targets .NET Standard 2.0+, fully compatible with net48
|
||||
- `required` keyword requires C# 11+ — on net48 (LangVersion 9.0), use properties with default values and validate in `ExecuteAsync` instead
|
||||
- `init` setters require C# 9+ (supported on net48 with LangVersion 9.0)
|
||||
- `async Task<int> Main` requires `System.Threading.Tasks` using directive on net48
|
||||
@@ -0,0 +1,172 @@
|
||||
# LLM Integration Guide
|
||||
|
||||
This document is the implemented machine-facing contract for using `graccess_cli` as an LLM automation layer for AVEVA/Wonderware System Platform IDE work through GRAccess.
|
||||
|
||||
The CLI still preserves legacy human output and existing `--json` shapes. LLMs should use `--llm-json` for a stable envelope.
|
||||
|
||||
## Stable Envelope
|
||||
|
||||
Galaxy-bound routed commands and LLM helper commands accept `--llm-json`.
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"command": "object snapshot",
|
||||
"galaxy": "ZB",
|
||||
"target": "TestMachine",
|
||||
"data": {},
|
||||
"commandResult": null,
|
||||
"warnings": [],
|
||||
"unavailable": [],
|
||||
"error": null,
|
||||
"exitCode": 0
|
||||
}
|
||||
```
|
||||
|
||||
Failures use the same envelope with `success=false`, `error`, and `exitCode`.
|
||||
|
||||
## Discovery
|
||||
|
||||
Use capabilities before generating plans:
|
||||
|
||||
```powershell
|
||||
graccess capabilities --json
|
||||
graccess capabilities --llm-json
|
||||
```
|
||||
|
||||
The capability registry is code-backed, not scraped from prose. It returns command name, dispatcher command/subcommand, argument metadata, mutation status, session routing support, confirmation target rule, and output schema name.
|
||||
|
||||
## Read Workflow
|
||||
|
||||
Prefer session mode for repeated reads:
|
||||
|
||||
```powershell
|
||||
graccess session start --galaxy ZB --node .
|
||||
graccess object snapshot --galaxy ZB --name TestMachine --type template --llm-json
|
||||
```
|
||||
|
||||
`object snapshot` includes object details, all attributes, configurable attributes, extended attributes, relationships, lineage, children, contained objects, package-backed attribute values/script bodies where available, and `Unavailable` entries for COM-backed sections that cannot be read safely.
|
||||
|
||||
Useful read commands:
|
||||
|
||||
```powershell
|
||||
graccess object get --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
|
||||
graccess object attribute value get --galaxy ZB --name TestMachine --type template --attribute Description --llm-json
|
||||
graccess object scripts list --galaxy ZB --name TestMachine --type template --llm-json
|
||||
graccess object scripts get --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --llm-json
|
||||
```
|
||||
|
||||
The CLI tries direct GRAccess reads first. If direct GRAccess does not expose inheritance, attribute values, or script bodies, read commands may export the target object to a temporary `.aaPKG`, parse textual/package entries, recurse into nested package archives, parse binary UTF-16 script extension records, and delete the temp files. SQL Server repository reads are not part of normal CLI behavior and should only be used for development verification/debugging.
|
||||
|
||||
Script body access is adapter-dependent. For `ScriptExtension` objects, a bare script name maps to `.ExecuteText`; `object scripts set` writes the matching script body attribute through GRAccess. Mutating script and attribute commands prefer `ConfigurableAttributes[...]` before `Attributes[...]`, because script extension settings such as `TriggerPeriod`, `TriggerType`, `Expression`, and `ExecuteText` are configuration attributes in common GRAccess builds. If neither direct GRAccess nor the package fallback exposes body text, script read commands return structured unavailable details instead of pretending success.
|
||||
|
||||
Use the script settings wrapper for IDE-style script configuration:
|
||||
|
||||
```powershell
|
||||
graccess object scripts settings set --galaxy ZB --name '$TestMachine' --type template --script UpdateTestChangingInt --trigger-period-ms 500 --lock-trigger-period --confirm --confirm-target '$TestMachine' --llm-json
|
||||
```
|
||||
|
||||
Use the create wrapper for new object-level script extensions:
|
||||
|
||||
```powershell
|
||||
graccess object scripts create --galaxy ZB --name '$MyTemplate' --type template --script OnScan --file OnScan.txt --trigger-type Periodic --trigger-period-ms 1000 --confirm --confirm-target '$MyTemplate' --llm-json
|
||||
```
|
||||
|
||||
## Inheritance And Embedded Objects
|
||||
|
||||
For template families, model inheritance and containment explicitly. Do not rely on a single field being populated by every GRAccess version.
|
||||
|
||||
```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
|
||||
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
|
||||
```
|
||||
|
||||
Read `data.Lineage`, `data.Children`, `data.ContainedObjects`, `data.Object.DerivedFrom`, `data.Object.BasedOn`, `ContainedName`, and `HierarchicalName` when available. The documented `ZB` `$TestMachine` family is an example: `$TestMachine` extends `$gMachine`, while `$TestMachine.DelmiaReceiver` and `$TestMachine.MESReceiver` are contained embedded templates.
|
||||
|
||||
Create derived templates and instances with contained objects when the family requires embedded children:
|
||||
|
||||
```powershell
|
||||
graccess template derive --galaxy ZB --name '$gMachine' --type template --new-name '$MyMachine' --confirm --confirm-target '$gMachine' --llm-json
|
||||
graccess template instantiate --galaxy ZB --name '$TestMachine' --type template --new-name TestMachine_021 --create-contained --confirm --confirm-target '$TestMachine' --llm-json
|
||||
```
|
||||
|
||||
Edit contained child templates or instances by targeting their own object names, such as `$TestMachine.DelmiaReceiver` or `DelmiaReceiver_001`, and use normal checkout/save/checkin safety.
|
||||
|
||||
## Validation And Batch
|
||||
|
||||
Per-command dry-run validates command shape and confirmation without calling mutating GRAccess methods:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
Plan validation:
|
||||
|
||||
```powershell
|
||||
graccess validate --request plan.json --llm-json
|
||||
```
|
||||
|
||||
Batch validation or execution:
|
||||
|
||||
```powershell
|
||||
graccess batch --file plan.json --mode validate --llm-json
|
||||
graccess batch --file plan.json --mode execute --llm-json
|
||||
```
|
||||
|
||||
Plan shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"Galaxy": "ZB",
|
||||
"Node": ".",
|
||||
"Commands": [
|
||||
{
|
||||
"Command": "object checkout",
|
||||
"Args": {
|
||||
"name": "TestMachine",
|
||||
"type": "template",
|
||||
"confirm": true,
|
||||
"confirm-target": "TestMachine"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Every mutating step must include its own `confirm=true` and exact `confirm-target`. There is no global mutation confirmation. Batch execute stops on first failure.
|
||||
|
||||
## IDE Intent Wrappers
|
||||
|
||||
Use intent-level commands instead of generic property edits when possible:
|
||||
|
||||
```powershell
|
||||
graccess area list --galaxy ZB --llm-json
|
||||
graccess area create --galaxy ZB --template '$Area' --name Area_Test --confirm --confirm-target '$Area' --llm-json
|
||||
graccess engine list --galaxy ZB --llm-json
|
||||
graccess engine create --galaxy ZB --template '$AppEngine' --name AppEngine_Test --confirm --confirm-target '$AppEngine' --llm-json
|
||||
graccess instance assign-area --galaxy ZB --name TestMachine_001 --area Area_Test --confirm --confirm-target TestMachine_001 --llm-json
|
||||
graccess instance assign-engine --galaxy ZB --name TestMachine_001 --engine AppEngine_Test --confirm --confirm-target TestMachine_001 --llm-json
|
||||
graccess instance assign-container --galaxy ZB --name TestMachine_001 --container ParentObject --confirm --confirm-target TestMachine_001 --llm-json
|
||||
graccess io assign --galaxy ZB --name TestMachine_001 --attribute DeviceAddress --value D100 --confirm --confirm-target TestMachine_001 --llm-json
|
||||
```
|
||||
|
||||
`object set --property area|host|container|toolset|security-group` attempts to resolve the named GRAccess object first, then falls back to raw string assignment for version-specific setters.
|
||||
|
||||
## Safety Rules
|
||||
|
||||
1. Start with `capabilities` and read-only snapshots.
|
||||
2. Do not mutate without an exact object or file target.
|
||||
3. Never use wildcard bulk mutation in production.
|
||||
4. Use `--dry-run --llm-json` before mutation plans.
|
||||
5. Snapshot before editing and re-read after editing.
|
||||
6. Stop after the first failed mutation or `CommandResult.Successful=false`.
|
||||
7. Treat missing or unavailable fields as unknown, not false.
|
||||
8. Prefer test objects or derived templates before production targets.
|
||||
9. Use session mode for repeated galaxy-bound commands.
|
||||
10. Use deployment commands only when the user explicitly names targets.
|
||||
@@ -0,0 +1,206 @@
|
||||
# Editing Scripts And Script Libraries
|
||||
|
||||
This guide describes how to edit scripts related to a template such as `TestMachine`.
|
||||
|
||||
Read `script-parsing.md` first so you know whether the target script is a script library, an object-level script-like attribute, an extension primitive, or content that only appears in an exported object package.
|
||||
|
||||
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 script work, read script metadata and validate guarded edits with the LLM envelope:
|
||||
|
||||
```powershell
|
||||
graccess object scripts list --galaxy ZB --name TestMachine --type template --llm-json
|
||||
graccess object scripts get --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --llm-json
|
||||
graccess object scripts set --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --file .\UpdateTestChangingInt.txt --confirm --confirm-target TestMachine --dry-run --llm-json
|
||||
```
|
||||
|
||||
## What The CLI Can Edit Today
|
||||
|
||||
| Area | Current command support |
|
||||
|---|---|
|
||||
| Script library inventory | `script-library list` |
|
||||
| Script library export | `script-library export` |
|
||||
| Script library import/add | `script-library import`, `script-library add`, `galaxy import-script-library` |
|
||||
| Object script metadata | `object scripts list`, `object scripts get` |
|
||||
| Object script body read/write | `object scripts get`, `object scripts set` for script body attributes such as `ExecuteText` |
|
||||
| Script-like attributes | `object attribute set`, lock, security, buffer |
|
||||
| Extension primitives | `object extension add/delete/rename` |
|
||||
| Full object package script payloads | Use `objects export` and `galaxy import-objects` |
|
||||
|
||||
## Export Before Editing
|
||||
|
||||
Export script libraries before changing them:
|
||||
|
||||
```powershell
|
||||
$out = '.\template-snapshots\script-libraries-before'
|
||||
New-Item -ItemType Directory -Force -Path $out | Out-Null
|
||||
|
||||
$libs = graccess script-library list --galaxy ZB --json | ConvertFrom-Json
|
||||
foreach ($lib in $libs) {
|
||||
$name = $lib.Name
|
||||
$path = Join-Path $out "$name.aaslib"
|
||||
graccess script-library export --galaxy ZB --name $name --output $path --confirm --confirm-target $path
|
||||
}
|
||||
```
|
||||
|
||||
Export the template package when object-level scripts may be involved:
|
||||
|
||||
```powershell
|
||||
$pkg = '.\template-snapshots\TestMachine-before\TestMachine.aaPKG'
|
||||
graccess objects export --galaxy ZB --type template --name TestMachine --output $pkg --confirm --confirm-target $pkg
|
||||
```
|
||||
|
||||
## Edit Script Libraries
|
||||
|
||||
Script library content is edited outside the CLI in the `.aaslib` file or source toolchain that creates it. Import the updated library after review:
|
||||
|
||||
```powershell
|
||||
graccess script-library import --galaxy ZB --path '.\scripts\CommonScripts.aaslib' --confirm --confirm-target '.\scripts\CommonScripts.aaslib'
|
||||
```
|
||||
|
||||
The galaxy-level import command is also available:
|
||||
|
||||
```powershell
|
||||
graccess galaxy import-script-library --galaxy ZB --path '.\scripts\CommonScripts.aaslib' --confirm --confirm-target '.\scripts\CommonScripts.aaslib'
|
||||
```
|
||||
|
||||
After import, list libraries again:
|
||||
|
||||
```powershell
|
||||
graccess script-library list --galaxy ZB --json
|
||||
```
|
||||
|
||||
## Edit Script-Like Attributes
|
||||
|
||||
Some templates store expressions, declarations, triggers, or script fragments in attributes. Find candidates:
|
||||
|
||||
```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
|
||||
$scripts = (@($attrs) + @($extended)) | Where-Object {
|
||||
$_.Name -match '(?i)script|execute|trigger|expression|declaration|startup|shutdown|scan'
|
||||
} | Sort-Object Name -Unique
|
||||
|
||||
$scripts | Select-Object Name, DataType, Category, Locked
|
||||
```
|
||||
|
||||
If the script-like setting is a scalar string attribute, edit it through the normal template edit flow. Script extension fields should be written through `ConfigurableAttributes`; the CLI does this automatically for `object scripts set`, `object scripts settings set`, and mutating `object attribute` commands. `object scripts set` is the convenience wrapper for script body attributes. A bare script name maps to `.ExecuteText`; explicit fields such as `.StartupText`, `.OnScanText`, or `.Expression` are preserved.
|
||||
|
||||
```powershell
|
||||
graccess object checkout --galaxy ZB --name TestMachine --type template --confirm --confirm-target TestMachine
|
||||
graccess object scripts set --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --file .\UpdateTestChangingInt.txt --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 script text' --confirm --confirm-target TestMachine
|
||||
```
|
||||
|
||||
Update periodic script settings and lock the interval for deployment inheritance:
|
||||
|
||||
```powershell
|
||||
graccess object checkout --galaxy ZB --name '$TestMachine' --type template --confirm --confirm-target '$TestMachine'
|
||||
graccess object scripts settings set --galaxy ZB --name '$TestMachine' --type template --script UpdateTestChangingInt --trigger-period-ms 500 --lock-trigger-period --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 'Set UpdateTestChangingInt interval to 500ms' --confirm --confirm-target '$TestMachine'
|
||||
```
|
||||
|
||||
Verify with package-backed readback:
|
||||
|
||||
```powershell
|
||||
graccess object scripts get --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --llm-json
|
||||
```
|
||||
|
||||
## Edit Extension Primitives
|
||||
|
||||
When a script is represented by an extension primitive, use the extension commands for the primitive lifecycle:
|
||||
|
||||
```powershell
|
||||
graccess object checkout --galaxy ZB --name TestMachine --type template --confirm --confirm-target TestMachine
|
||||
graccess object extension add --galaxy ZB --name TestMachine --type template --extension-type ScriptExtension --primitive OnScan --object-extension --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 script extension primitive' --confirm --confirm-target TestMachine
|
||||
```
|
||||
|
||||
Rename:
|
||||
|
||||
```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:
|
||||
|
||||
```powershell
|
||||
graccess object extension delete --galaxy ZB --name TestMachine --type template --extension-type ScriptExtension --primitive OnScan2 --object-extension --confirm --confirm-target TestMachine
|
||||
```
|
||||
|
||||
These commands manage primitive structure. The IDE-oriented wrapper below creates the same `ScriptExtension` primitive and can initialize the body and common settings:
|
||||
|
||||
```powershell
|
||||
graccess object checkout --galaxy ZB --name '$MyTemplate' --type template --confirm --confirm-target '$MyTemplate'
|
||||
graccess object scripts create --galaxy ZB --name '$MyTemplate' --type template --script OnScan --file .\OnScan.txt --trigger-type Periodic --trigger-period-ms 1000 --confirm --confirm-target '$MyTemplate'
|
||||
graccess object save --galaxy ZB --name '$MyTemplate' --type template --confirm --confirm-target '$MyTemplate'
|
||||
graccess object checkin --galaxy ZB --name '$MyTemplate' --type template --comment 'Add OnScan script' --confirm --confirm-target '$MyTemplate'
|
||||
```
|
||||
|
||||
After adding a `ScriptExtension` primitive, set its body with `object scripts set --script <primitiveName>` or `object scripts set --script <primitiveName>.ExecuteText`.
|
||||
|
||||
## Full-Fidelity Object Script Edits
|
||||
|
||||
When script bodies are only available inside the object package, use export/import:
|
||||
|
||||
1. Export the template package.
|
||||
2. Edit with the supported vendor tooling or package workflow.
|
||||
3. Import the updated package with explicit confirmation.
|
||||
4. Re-parse and validate the template.
|
||||
|
||||
Export:
|
||||
|
||||
```powershell
|
||||
$pkg = '.\template-work\TestMachine.aaPKG'
|
||||
graccess objects export --galaxy ZB --type template --name TestMachine --output $pkg --confirm --confirm-target $pkg
|
||||
```
|
||||
|
||||
Import:
|
||||
|
||||
```powershell
|
||||
graccess galaxy import-objects --galaxy ZB --file '.\template-work\TestMachine.aaPKG' --overwrite --confirm --confirm-target '.\template-work\TestMachine.aaPKG'
|
||||
```
|
||||
|
||||
For conflict-aware import:
|
||||
|
||||
```powershell
|
||||
graccess galaxy import-objects-ex --galaxy ZB --file '.\template-work\TestMachine.aaPKG' --version-conflict '<E_RESOLVE_VERSION_CONFLICT_ACTION>' --name-conflict '<E_RESOLVE_NAME_CONFLICT_ACTION>' --confirm --confirm-target '.\template-work\TestMachine.aaPKG'
|
||||
```
|
||||
|
||||
The exact enum values for import conflict handling must match the local GRAccess interop assembly. See `graccess_operations.md` and `graccess_documentation.md`.
|
||||
|
||||
## Validate Script Edits
|
||||
|
||||
After import or checkin:
|
||||
|
||||
```powershell
|
||||
graccess object get --galaxy ZB --name TestMachine --type template --json
|
||||
graccess object attributes --galaxy ZB --name TestMachine --type template --json
|
||||
graccess object extended-attributes --galaxy ZB --name TestMachine --type template --json
|
||||
```
|
||||
|
||||
For runtime validation, instantiate a test object and deploy only that explicitly named test instance:
|
||||
|
||||
```powershell
|
||||
graccess template instantiate --galaxy ZB --name TestMachine --type template --new-name TestMachine_ScriptTest_001 --create-contained --confirm --confirm-target TestMachine
|
||||
graccess instance deploy --galaxy ZB --name TestMachine_ScriptTest_001 --type instance --confirm --confirm-target TestMachine_ScriptTest_001
|
||||
```
|
||||
|
||||
## Supported Object Script Command Pattern
|
||||
|
||||
```text
|
||||
graccess object scripts list --galaxy ZB --name TestMachine --type template --json
|
||||
graccess object scripts get --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --llm-json
|
||||
graccess object scripts set --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --file .\UpdateTestChangingInt.txt --confirm --confirm-target TestMachine --llm-json
|
||||
```
|
||||
|
||||
The local GRAccess examples sometimes show `Template.Scripts[index].ScriptString`. This repository's installed interop exposes the same practical content through script extension attributes such as `UpdateTestChangingInt.ExecuteText`; the CLI writes those attributes directly via `IAttribute.SetValue`.
|
||||
@@ -0,0 +1,130 @@
|
||||
# Parsing Scripts And Script Libraries
|
||||
|
||||
This guide describes how to capture scripts related to a template such as `TestMachine`.
|
||||
|
||||
GRAccess exposes script libraries directly through `IScriptLibraries` and `IScriptLibrary`. Object-level scripts are less direct: depending on object type and System Platform version, they may appear as attributes, extension attributes, or only inside exported object packages.
|
||||
|
||||
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 workflows, include object script metadata in the snapshot first:
|
||||
|
||||
```powershell
|
||||
graccess object snapshot --galaxy ZB --name TestMachine --type template --llm-json
|
||||
graccess object scripts list --galaxy ZB --name TestMachine --type template --llm-json
|
||||
graccess object scripts get --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt.ExecuteText --llm-json
|
||||
graccess object scripts get --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --llm-json
|
||||
```
|
||||
|
||||
Direct object script body readback is version-specific. The CLI tries direct GRAccess metadata first, then exports the target object to a temporary `.aaPKG`, recurses through nested package archives, and parses binary UTF-16 package records for `ScriptExtension` content. For script extension names, a bare script such as `UpdateTestChangingInt` resolves to `UpdateTestChangingInt.ExecuteText`. Explicit fields such as `UpdateTestChangingInt.StartupText` are preserved.
|
||||
|
||||
The exported package fallback can read script text fields such as `ExecuteText`, `DeclarationsText`, `StartupText`, `ShutdownText`, `OnScanText`, `OffScanText`, and `Expression` when present. When body access is unavailable from both direct GRAccess and package data, `object scripts get` reports that in structured output.
|
||||
|
||||
## Script Library Inventory
|
||||
|
||||
List script libraries:
|
||||
|
||||
```powershell
|
||||
graccess script-library list --galaxy ZB --json
|
||||
```
|
||||
|
||||
The current CLI returns library names. The underlying GRAccess API for `IScriptLibrary` exposes `Name` and `Export(path)`.
|
||||
|
||||
## Export Script Libraries
|
||||
|
||||
Export is the authoritative way to preserve script library content:
|
||||
|
||||
```powershell
|
||||
$out = '.\template-snapshots\script-libraries'
|
||||
New-Item -ItemType Directory -Force -Path $out | Out-Null
|
||||
|
||||
graccess script-library export --galaxy ZB --name CommonScripts --output "$out\CommonScripts.aaslib" --confirm --confirm-target "$out\CommonScripts.aaslib"
|
||||
```
|
||||
|
||||
`script-library export` writes a local file, so the CLI requires confirmation and a matching `--confirm-target` equal to the output path.
|
||||
|
||||
To export every listed script library, parse the JSON list and call export for each name:
|
||||
|
||||
```powershell
|
||||
$galaxy = 'ZB'
|
||||
$out = '.\template-snapshots\script-libraries'
|
||||
New-Item -ItemType Directory -Force -Path $out | Out-Null
|
||||
|
||||
$libs = graccess script-library list --galaxy $galaxy --json | ConvertFrom-Json
|
||||
foreach ($lib in $libs) {
|
||||
$name = $lib.Name
|
||||
$path = Join-Path $out "$name.aaslib"
|
||||
graccess script-library export --galaxy $galaxy --name $name --output $path --confirm --confirm-target $path
|
||||
}
|
||||
```
|
||||
|
||||
## Object-Level Script Discovery
|
||||
|
||||
For a template such as `TestMachine`, first inspect attributes and extended attributes for script-like names:
|
||||
|
||||
```powershell
|
||||
graccess object attributes --galaxy ZB --name TestMachine --type template --json
|
||||
graccess object extended-attributes --galaxy ZB --name TestMachine --type template --json
|
||||
```
|
||||
|
||||
PowerShell classification:
|
||||
|
||||
```powershell
|
||||
$attrs = Get-Content '.\template-snapshots\TestMachine.attributes.json' -Raw | ConvertFrom-Json
|
||||
$extended = Get-Content '.\template-snapshots\TestMachine.extended-attributes.json' -Raw | ConvertFrom-Json
|
||||
$all = (@($attrs) + @($extended)) | Sort-Object Name -Unique
|
||||
|
||||
$scripts = $all | Where-Object {
|
||||
$_.Name -match '(?i)script|execute|trigger|expression|declaration|startup|shutdown|scan'
|
||||
}
|
||||
|
||||
$scripts | Sort-Object Name | Select-Object Name, DataType, Category, Locked
|
||||
```
|
||||
|
||||
This discovers script-related setting names and metadata. For bodies, prefer `object scripts get --llm-json` or `object snapshot --llm-json`; both can include package-backed script text when GRAccess export is available. Normal CLI script parsing must not query the Galaxy SQL database; SQL is development verification/debug-only.
|
||||
|
||||
## Export Template Objects For Script Bodies
|
||||
|
||||
Use object export when you need the full object configuration, including script bodies, declarations, triggers, and extension payloads that are not exposed as simple attribute metadata:
|
||||
|
||||
```powershell
|
||||
$out = '.\template-snapshots\TestMachine'
|
||||
New-Item -ItemType Directory -Force -Path $out | Out-Null
|
||||
$pkg = Join-Path $out 'TestMachine.aaPKG'
|
||||
|
||||
graccess objects export --galaxy ZB --type template --name TestMachine --output $pkg --confirm --confirm-target $pkg
|
||||
```
|
||||
|
||||
The exported package should be treated as the complete vendor-owned representation. Use it as the source of truth when CLI JSON and GRAccess attribute metadata do not expose script content.
|
||||
|
||||
For a galaxy-wide reference export:
|
||||
|
||||
```powershell
|
||||
$pkg = '.\template-snapshots\ZB.export.aaPKG'
|
||||
graccess galaxy export-all --galaxy ZB --output $pkg --json
|
||||
```
|
||||
|
||||
`galaxy export-all` is read-only from the galaxy perspective but writes an output file.
|
||||
|
||||
## Suggested Parse Bundle
|
||||
|
||||
A practical template parse bundle should include:
|
||||
|
||||
| File | Command |
|
||||
|---|---|
|
||||
| `object.json` | `object get` |
|
||||
| `attributes.json` | `object attributes` |
|
||||
| `configurable-attributes.json` | `object attributes --configurable` |
|
||||
| `extended-attributes.json` | `object extended-attributes` |
|
||||
| `attribute-groups.json` | Local classifier from `attribute-parsing.md` |
|
||||
| `template.aaPKG` | `objects export` |
|
||||
| `script-libraries/*.aaslib` | `script-library export` |
|
||||
|
||||
## Notes On GRAccess Script Collections
|
||||
|
||||
Some GRAccess examples refer to `Template.Scripts[index].ScriptString`. The local installed GRAccess interop and docs used by this CLI expose `ScriptExtension` content through script-like attributes and exported package records instead. Use `object scripts list/get` as the supported discovery and readback contract for this repository.
|
||||
@@ -0,0 +1,370 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,441 @@
|
||||
# Creating And Editing Template Instances
|
||||
|
||||
This guide describes how to create and edit instances from templates with `graccess_cli`, including area creation, area assignment, engine assignment, I/O-related configuration, deployment, and rollback.
|
||||
|
||||
Use this guide with:
|
||||
|
||||
- `template-parsing.md` - inspect templates before instantiation.
|
||||
- `template-editing.md` - edit source templates.
|
||||
- `attribute-parsing.md` and `attribute-editing.md` - inspect and edit instance settings.
|
||||
- `script-parsing.md` and `script-editing.md` - inspect and edit script-related content.
|
||||
|
||||
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
|
||||
|
||||
Mutating commands require `--confirm`. Commands that edit an object require `--confirm-target` matching the exact current object name.
|
||||
|
||||
Important confirmation targets:
|
||||
|
||||
| Command | `--confirm-target` must match |
|
||||
|---|---|
|
||||
| `template instantiate` | Source template name |
|
||||
| `object checkout/save/checkin/undo-checkout` | Target object or instance name |
|
||||
| `object set` | Target object or instance name |
|
||||
| `object attribute set/lock/security/buffer` | Target object or instance name |
|
||||
| `object attribute value set` | Target object or instance name |
|
||||
| `instance assign-area/assign-engine/assign-container` | Target instance name |
|
||||
| `io assign` | Target instance name |
|
||||
| `instance deploy/undeploy/upload/delete` | Target instance name |
|
||||
| `objects export` | Output file path |
|
||||
| `galaxy import-objects` | Input file path |
|
||||
|
||||
For production work, create or use a test area and test instance first.
|
||||
|
||||
## Session Setup
|
||||
|
||||
Start a session for repeated work:
|
||||
|
||||
```powershell
|
||||
graccess session start --galaxy ZB --node .
|
||||
```
|
||||
|
||||
With a session active, omit `--node` on logged-in commands. Without a session, add `--node .` to each command.
|
||||
|
||||
For LLM-driven instance work, snapshot before and after edits:
|
||||
|
||||
```powershell
|
||||
graccess object snapshot --galaxy ZB --name TestMachine_001 --type instance --llm-json
|
||||
```
|
||||
|
||||
Prefer intent wrappers for IDE concepts:
|
||||
|
||||
```powershell
|
||||
graccess area list --galaxy ZB --llm-json
|
||||
graccess engine list --galaxy ZB --llm-json
|
||||
graccess instance assign-area --galaxy ZB --name TestMachine_001 --area Area_Test --confirm --confirm-target TestMachine_001 --llm-json
|
||||
graccess instance assign-engine --galaxy ZB --name TestMachine_001 --engine AppEngine_Test --confirm --confirm-target TestMachine_001 --llm-json
|
||||
graccess io assign --galaxy ZB --name TestMachine_001 --attribute DeviceAddress --value D100 --confirm --confirm-target TestMachine_001 --llm-json
|
||||
```
|
||||
|
||||
## Discover Source Templates
|
||||
|
||||
Find the exact template name before instantiation:
|
||||
|
||||
```powershell
|
||||
graccess template list --galaxy ZB --pattern '%TestMachine%' --json
|
||||
```
|
||||
|
||||
If the template starts with `$`, quote it in PowerShell:
|
||||
|
||||
```powershell
|
||||
graccess template list --galaxy ZB --pattern '%$Area%' --json
|
||||
graccess template list --galaxy ZB --pattern '%$AppEngine%' --json
|
||||
```
|
||||
|
||||
Template names differ by System Platform version and galaxy standards. Always confirm the actual template names in the target galaxy.
|
||||
|
||||
## Create An Instance From A Template
|
||||
|
||||
Use `template instantiate`:
|
||||
|
||||
```powershell
|
||||
graccess template instantiate --galaxy ZB --name TestMachine --type template --new-name TestMachine_001 --create-contained --confirm --confirm-target TestMachine
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
| Option | Meaning |
|
||||
|---|---|
|
||||
| `--name` | Source template name |
|
||||
| `--new-name` | New instance tagname |
|
||||
| `--create-contained` | Create contained objects from the template when supported |
|
||||
| `--confirm-target` | Must match the source template name |
|
||||
|
||||
Verify the new instance:
|
||||
|
||||
```powershell
|
||||
graccess object get --galaxy ZB --name TestMachine_001 --type instance --json
|
||||
graccess object attributes --galaxy ZB --name TestMachine_001 --type instance --json
|
||||
```
|
||||
|
||||
## Create Areas
|
||||
|
||||
Areas are galaxy objects. The CLI has an `area create` wrapper and also supports the underlying `template instantiate` workflow. Prefer the wrapper when it maps cleanly to the target galaxy; fall back to `template instantiate` when you need explicit control over the source template.
|
||||
|
||||
Find candidate area templates:
|
||||
|
||||
```powershell
|
||||
graccess template list --galaxy ZB --pattern '%Area%' --json
|
||||
```
|
||||
|
||||
Create an area instance, using the exact area template name returned by the galaxy. If the template is `$Area`, quote it:
|
||||
|
||||
```powershell
|
||||
graccess area create --galaxy ZB --template '$Area' --name Area_Test --confirm --confirm-target '$Area' --llm-json
|
||||
```
|
||||
|
||||
Equivalent lower-level form:
|
||||
|
||||
```powershell
|
||||
graccess template instantiate --galaxy ZB --name '$Area' --type template --new-name Area_Test --create-contained --confirm --confirm-target '$Area'
|
||||
```
|
||||
|
||||
Verify the area:
|
||||
|
||||
```powershell
|
||||
graccess object get --galaxy ZB --name Area_Test --type instance --json
|
||||
```
|
||||
|
||||
Edit an area like any other instance:
|
||||
|
||||
```powershell
|
||||
graccess object checkout --galaxy ZB --name Area_Test --type instance --confirm --confirm-target Area_Test
|
||||
graccess object attribute set --galaxy ZB --name Area_Test --type instance --attribute Description --value 'Test area' --data-type string --confirm --confirm-target Area_Test
|
||||
graccess object save --galaxy ZB --name Area_Test --type instance --confirm --confirm-target Area_Test
|
||||
graccess object checkin --galaxy ZB --name Area_Test --type instance --comment 'Configure test area' --confirm --confirm-target Area_Test
|
||||
```
|
||||
|
||||
If the area template or area attributes differ in the target galaxy, use the parsing docs to identify the supported attributes before editing.
|
||||
|
||||
## Assign An Instance To An Area
|
||||
|
||||
Use `object set --property area` on the instance:
|
||||
|
||||
```powershell
|
||||
graccess object checkout --galaxy ZB --name TestMachine_001 --type instance --confirm --confirm-target TestMachine_001
|
||||
graccess object set --galaxy ZB --name TestMachine_001 --type instance --property area --value Area_Test --confirm --confirm-target TestMachine_001
|
||||
graccess object save --galaxy ZB --name TestMachine_001 --type instance --confirm --confirm-target TestMachine_001
|
||||
graccess object checkin --galaxy ZB --name TestMachine_001 --type instance --comment 'Assign area' --confirm --confirm-target TestMachine_001
|
||||
```
|
||||
|
||||
Validate area relationships:
|
||||
|
||||
```powershell
|
||||
graccess object query-condition --galaxy ZB --type instance --condition belongsToArea --value Area_Test --json
|
||||
```
|
||||
|
||||
The current CLI resolves named GRAccess objects before falling back to string assignment for object-reference properties such as `area`, `host`, and `container`.
|
||||
|
||||
## Create Or Find Engines
|
||||
|
||||
Engine creation is also template-driven. The CLI has an `engine create` wrapper and also supports the underlying `template instantiate` workflow.
|
||||
|
||||
Find engine templates:
|
||||
|
||||
```powershell
|
||||
graccess template list --galaxy ZB --pattern '%Engine%' --json
|
||||
```
|
||||
|
||||
Create an engine instance only after confirming the correct platform/engine template for the target galaxy:
|
||||
|
||||
```powershell
|
||||
graccess engine create --galaxy ZB --template '$AppEngine' --name AppEngine_Test --confirm --confirm-target '$AppEngine' --llm-json
|
||||
```
|
||||
|
||||
Equivalent lower-level form:
|
||||
|
||||
```powershell
|
||||
graccess template instantiate --galaxy ZB --name '$AppEngine' --type template --new-name AppEngine_Test --create-contained --confirm --confirm-target '$AppEngine'
|
||||
```
|
||||
|
||||
If the galaxy already has a target engine, inspect it instead:
|
||||
|
||||
```powershell
|
||||
graccess object get --galaxy ZB --name AppEngine_Test --type instance --json
|
||||
graccess object attributes --galaxy ZB --name AppEngine_Test --type instance --json
|
||||
```
|
||||
|
||||
Engine templates and required container/platform relationships vary by System Platform version and galaxy standards. Use export/import or vendor tooling if engine creation requires fields the CLI does not expose yet.
|
||||
|
||||
## Assign An Instance To An Engine
|
||||
|
||||
Use `object set --property host`:
|
||||
|
||||
```powershell
|
||||
graccess object checkout --galaxy ZB --name TestMachine_001 --type instance --confirm --confirm-target TestMachine_001
|
||||
graccess object set --galaxy ZB --name TestMachine_001 --type instance --property host --value AppEngine_Test --confirm --confirm-target TestMachine_001
|
||||
graccess object save --galaxy ZB --name TestMachine_001 --type instance --confirm --confirm-target TestMachine_001
|
||||
graccess object checkin --galaxy ZB --name TestMachine_001 --type instance --comment 'Assign host engine' --confirm --confirm-target TestMachine_001
|
||||
```
|
||||
|
||||
Validate engine assignment:
|
||||
|
||||
```powershell
|
||||
graccess object query-condition --galaxy ZB --type instance --condition hostEngineIs --value AppEngine_Test --json
|
||||
```
|
||||
|
||||
The current CLI resolves named GRAccess objects before falling back to string assignment for object-reference properties.
|
||||
|
||||
## Assign Container Or Parent Object
|
||||
|
||||
Use `object set --property container` when the instance should be contained by another object:
|
||||
|
||||
```powershell
|
||||
graccess object checkout --galaxy ZB --name TestMachine_001 --type instance --confirm --confirm-target TestMachine_001
|
||||
graccess object set --galaxy ZB --name TestMachine_001 --type instance --property container --value Area_Test --confirm --confirm-target TestMachine_001
|
||||
graccess object save --galaxy ZB --name TestMachine_001 --type instance --confirm --confirm-target TestMachine_001
|
||||
graccess object checkin --galaxy ZB --name TestMachine_001 --type instance --comment 'Assign container' --confirm --confirm-target TestMachine_001
|
||||
```
|
||||
|
||||
Validate containment:
|
||||
|
||||
```powershell
|
||||
graccess object query-condition --galaxy ZB --type instance --condition containedBy --value Area_Test --json
|
||||
```
|
||||
|
||||
Container, area, and host are separate concepts. Use the property that matches the object model requirement for the template being instantiated.
|
||||
|
||||
## Create And Edit Embedded Objects
|
||||
|
||||
Embedded objects are contained child templates or instances. In the `TestMachine` family, `$TestMachine` contains `$TestMachine.DelmiaReceiver` and `$TestMachine.MESReceiver`; each `TestMachine_NNN` instance contains `DelmiaReceiver_NNN` and `MESReceiver_NNN`.
|
||||
|
||||
Create embedded objects by instantiating the parent with `--create-contained`:
|
||||
|
||||
```powershell
|
||||
graccess template instantiate --galaxy ZB --name '$TestMachine' --type template --new-name TestMachine_021 --create-contained --confirm --confirm-target '$TestMachine' --llm-json
|
||||
```
|
||||
|
||||
Verify parent and child objects:
|
||||
|
||||
```powershell
|
||||
graccess object snapshot --galaxy ZB --name TestMachine_021 --type instance --llm-json
|
||||
graccess instance list --galaxy ZB --pattern '%021%' --llm-json
|
||||
graccess object query-condition --galaxy ZB --type instance --condition hierarchicalNameLike --value '%TestMachine_021%' --llm-json
|
||||
```
|
||||
|
||||
If relationship queries do not return the embedded children, fall back to instance list patterns and child naming conventions:
|
||||
|
||||
```powershell
|
||||
graccess instance list --galaxy ZB --pattern '%DelmiaReceiver_021%' --llm-json
|
||||
graccess instance list --galaxy ZB --pattern '%MESReceiver_021%' --llm-json
|
||||
```
|
||||
|
||||
Edit embedded child instances by targeting the child instance tagname:
|
||||
|
||||
```powershell
|
||||
graccess object snapshot --galaxy ZB --name DelmiaReceiver_021 --type instance --llm-json
|
||||
graccess object checkout --galaxy ZB --name DelmiaReceiver_021 --type instance --confirm --confirm-target DelmiaReceiver_021
|
||||
graccess object attribute value set --galaxy ZB --name DelmiaReceiver_021 --type instance --attribute DownloadPath --value 'C:\Recipes\021' --data-type string --confirm --confirm-target DelmiaReceiver_021 --llm-json
|
||||
graccess object save --galaxy ZB --name DelmiaReceiver_021 --type instance --confirm --confirm-target DelmiaReceiver_021
|
||||
graccess object checkin --galaxy ZB --name DelmiaReceiver_021 --type instance --comment 'Configure embedded Delmia receiver' --confirm --confirm-target DelmiaReceiver_021
|
||||
```
|
||||
|
||||
Assign or move containment with `instance assign-container` or `object set --property container` only when the target object model supports moving that object:
|
||||
|
||||
```powershell
|
||||
graccess instance assign-container --galaxy ZB --name DelmiaReceiver_021 --container TestMachine_021 --confirm --confirm-target DelmiaReceiver_021 --llm-json
|
||||
```
|
||||
|
||||
Do not assume embedded child tag names are globally derivable from the parent number in every galaxy. Always verify `ContainedName` and `HierarchicalName` with `object snapshot`.
|
||||
|
||||
## Assign I/O
|
||||
|
||||
I/O assignment can mean different things depending on the template:
|
||||
|
||||
| I/O concern | Usual configuration path |
|
||||
|---|---|
|
||||
| Host engine | `object set --property host` |
|
||||
| Area | `object set --property area` |
|
||||
| Parent/container | `object set --property container` |
|
||||
| Device/topic/address/reference settings | Attribute values or extension payloads |
|
||||
| Complex I/O object structure | Instantiate I/O templates, set relationships, or import package |
|
||||
|
||||
First parse likely I/O settings:
|
||||
|
||||
```powershell
|
||||
$attrs = graccess object attributes --galaxy ZB --name TestMachine_001 --type instance --json | ConvertFrom-Json
|
||||
$extended = graccess object extended-attributes --galaxy ZB --name TestMachine_001 --type instance --json | ConvertFrom-Json
|
||||
$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 I/O attributes:
|
||||
|
||||
```powershell
|
||||
graccess object checkout --galaxy ZB --name TestMachine_001 --type instance --confirm --confirm-target TestMachine_001
|
||||
graccess object attribute set --galaxy ZB --name TestMachine_001 --type instance --attribute DeviceAddress --value 'D100' --data-type string --confirm --confirm-target TestMachine_001
|
||||
graccess object attribute set --galaxy ZB --name TestMachine_001 --type instance --attribute ScanPeriod --value 1000 --data-type int --confirm --confirm-target TestMachine_001
|
||||
graccess object save --galaxy ZB --name TestMachine_001 --type instance --confirm --confirm-target TestMachine_001
|
||||
graccess object checkin --galaxy ZB --name TestMachine_001 --type instance --comment 'Assign I/O settings' --confirm --confirm-target TestMachine_001
|
||||
```
|
||||
|
||||
The exact attribute names are template-specific. Use `attribute-parsing.md` to identify real names before editing.
|
||||
|
||||
The current CLI supports scalar attribute values only: `string`, `bool`, `int`, `float`, and `double`. Complex I/O settings such as object references, arrays, structured addresses, or extension-specific payloads may require object export/import or additional CLI value serialization.
|
||||
|
||||
## Edit Instance Attributes
|
||||
|
||||
For normal instance configuration:
|
||||
|
||||
```powershell
|
||||
graccess object checkout --galaxy ZB --name TestMachine_001 --type instance --confirm --confirm-target TestMachine_001
|
||||
|
||||
graccess object attribute set --galaxy ZB --name TestMachine_001 --type instance --attribute Description --value 'Machine 001' --data-type string --confirm --confirm-target TestMachine_001
|
||||
|
||||
graccess object attribute security --galaxy ZB --name TestMachine_001 --type instance --attribute Description --security MxSecurityOperate --confirm --confirm-target TestMachine_001
|
||||
|
||||
graccess object save --galaxy ZB --name TestMachine_001 --type instance --confirm --confirm-target TestMachine_001
|
||||
graccess object checkin --galaxy ZB --name TestMachine_001 --type instance --comment 'Configure instance' --confirm --confirm-target TestMachine_001
|
||||
```
|
||||
|
||||
For a deeper attribute workflow, use `attribute-editing.md`.
|
||||
|
||||
## Deploy, Undeploy, And Upload
|
||||
|
||||
Deploy an explicitly named test instance:
|
||||
|
||||
```powershell
|
||||
graccess instance deploy --galaxy ZB --name TestMachine_001 --type instance --confirm --confirm-target TestMachine_001
|
||||
```
|
||||
|
||||
Undeploy:
|
||||
|
||||
```powershell
|
||||
graccess instance undeploy --galaxy ZB --name TestMachine_001 --type instance --confirm --confirm-target TestMachine_001
|
||||
```
|
||||
|
||||
Upload runtime changes:
|
||||
|
||||
```powershell
|
||||
graccess instance upload --galaxy ZB --name TestMachine_001 --type instance --confirm --confirm-target TestMachine_001
|
||||
```
|
||||
|
||||
Bulk deployment commands are available, but use them only with explicit target selection:
|
||||
|
||||
```powershell
|
||||
graccess objects deploy --galaxy ZB --type instance --name TestMachine_001 --name TestMachine_002 --confirm --confirm-target TestMachine_001,TestMachine_002
|
||||
```
|
||||
|
||||
For bulk commands, the confirmation target must match the CLI's target list. Prefer single-instance deployment until the target list behavior is verified in a test galaxy.
|
||||
|
||||
## Export Instance Configuration
|
||||
|
||||
Export before risky edits:
|
||||
|
||||
```powershell
|
||||
$pkg = '.\instance-snapshots\TestMachine_001-before.aaPKG'
|
||||
graccess objects export --galaxy ZB --type instance --name TestMachine_001 --output $pkg --confirm --confirm-target $pkg
|
||||
```
|
||||
|
||||
For full-fidelity edits not supported by scalar CLI commands, edit through the supported package workflow and import:
|
||||
|
||||
```powershell
|
||||
graccess galaxy import-objects --galaxy ZB --file '.\instance-snapshots\TestMachine_001-edited.aaPKG' --overwrite --confirm --confirm-target '.\instance-snapshots\TestMachine_001-edited.aaPKG'
|
||||
```
|
||||
|
||||
## Delete Test Instances
|
||||
|
||||
Delete only explicitly named test instances:
|
||||
|
||||
```powershell
|
||||
graccess instance delete --galaxy ZB --name TestMachine_001 --type instance --confirm --confirm-target TestMachine_001
|
||||
```
|
||||
|
||||
If the object is deployed, undeploy it first unless the selected force option explicitly allows deletion. The command exposes `--force-option`; the default is `undeployIfDeployed`.
|
||||
|
||||
```powershell
|
||||
graccess instance delete --galaxy ZB --name TestMachine_001 --type instance --force-option undeployIfDeployed --confirm --confirm-target TestMachine_001
|
||||
```
|
||||
|
||||
## End-To-End Example
|
||||
|
||||
This creates an area, creates a template instance, assigns area and engine, sets simple I/O attributes, and deploys the instance.
|
||||
|
||||
```powershell
|
||||
$galaxy = 'ZB'
|
||||
$template = 'TestMachine'
|
||||
$areaTemplate = '$Area'
|
||||
$area = 'Area_Test'
|
||||
$engine = 'AppEngine_Test'
|
||||
$instance = 'TestMachine_001'
|
||||
|
||||
graccess session start --galaxy $galaxy --node .
|
||||
|
||||
graccess template instantiate --galaxy $galaxy --name $areaTemplate --type template --new-name $area --create-contained --confirm --confirm-target $areaTemplate
|
||||
|
||||
graccess template instantiate --galaxy $galaxy --name $template --type template --new-name $instance --create-contained --confirm --confirm-target $template
|
||||
|
||||
graccess object checkout --galaxy $galaxy --name $instance --type instance --confirm --confirm-target $instance
|
||||
graccess object set --galaxy $galaxy --name $instance --type instance --property area --value $area --confirm --confirm-target $instance
|
||||
graccess object set --galaxy $galaxy --name $instance --type instance --property host --value $engine --confirm --confirm-target $instance
|
||||
graccess object attribute set --galaxy $galaxy --name $instance --type instance --attribute DeviceAddress --value 'D100' --data-type string --confirm --confirm-target $instance
|
||||
graccess object attribute set --galaxy $galaxy --name $instance --type instance --attribute ScanPeriod --value 1000 --data-type int --confirm --confirm-target $instance
|
||||
graccess object save --galaxy $galaxy --name $instance --type instance --confirm --confirm-target $instance
|
||||
graccess object checkin --galaxy $galaxy --name $instance --type instance --comment 'Create and configure test instance' --confirm --confirm-target $instance
|
||||
|
||||
graccess instance deploy --galaxy $galaxy --name $instance --type instance --confirm --confirm-target $instance
|
||||
```
|
||||
|
||||
Before running this exact sequence, verify `$Area`, `AppEngine_Test`, `DeviceAddress`, and `ScanPeriod` are valid in the target galaxy. These names are examples, not universal System Platform requirements.
|
||||
|
||||
## Post-Edit Verification
|
||||
|
||||
Verify object records and relationships:
|
||||
|
||||
```powershell
|
||||
graccess object get --galaxy ZB --name TestMachine_001 --type instance --json
|
||||
graccess object attributes --galaxy ZB --name TestMachine_001 --type instance --configurable --json
|
||||
graccess object query-condition --galaxy ZB --type instance --condition belongsToArea --value Area_Test --json
|
||||
graccess object query-condition --galaxy ZB --type instance --condition hostEngineIs --value AppEngine_Test --json
|
||||
```
|
||||
|
||||
If deployed, verify deployment status through available object details or System Platform tooling. The current `object get` output does not emit every `IInstance` status property; extending object details to include `DeploymentStatus`, `DeployedVersion`, validation errors, and warnings is recommended.
|
||||
|
||||
## Current CLI Gaps For Instance Work
|
||||
|
||||
| Area | Current status | Recommended next step |
|
||||
|---|---|---|
|
||||
| Dedicated area commands | Areas are created and edited as normal instances | Add `area create/edit/list` wrappers if desired |
|
||||
| Dedicated engine commands | Engines are created and edited as normal instances | Add `engine create/edit/list` wrappers if desired |
|
||||
| Object-reference assignment | `object set` currently writes the supplied value directly | Resolve named objects and assign COM object references when required |
|
||||
| Bulk property edits | Bulk deploy/undeploy/upload/delete/export exist; bulk `area`/`host` assignment does not | Add guarded `objects set` after single-object assignment is reliable |
|
||||
| Complex I/O values | Scalar `MxValue` writes only | Add array/reference/structured value serialization |
|
||||
| Deployment status details | `object get` does not emit all instance status fields | Extend object detail output defensively |
|
||||
@@ -0,0 +1,275 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,435 @@
|
||||
# GRAccess CLI Usage
|
||||
|
||||
Command-line interface for Aveva System Platform Galaxy management via the GRAccess library.
|
||||
|
||||
## Global Options
|
||||
|
||||
All commands that interact with a galaxy require:
|
||||
|
||||
| Option | Short | Description | Required |
|
||||
|---|---|---|---|
|
||||
| `--galaxy` | `-g` | Galaxy name | Yes |
|
||||
| `--node` | `-n` | GR node name. Blank defaults to local node; `.` is normalized to the local machine name. | One-shot mode only |
|
||||
|
||||
In session mode, `--node` is not needed because the daemon already holds the connection.
|
||||
|
||||
Machine-facing commands also support:
|
||||
|
||||
| Option | Description |
|
||||
|---|---|
|
||||
| `--json` | Legacy command-specific JSON. Existing shapes are preserved. |
|
||||
| `--llm-json` | Stable success/error envelope for LLM and tool callers. |
|
||||
| `--dry-run` | For mutating routed commands, validate arguments and confirmation without invoking mutating GRAccess calls. |
|
||||
|
||||
`--llm-json` envelope shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"command": "object get",
|
||||
"galaxy": "ZB",
|
||||
"target": "TestMachine",
|
||||
"data": {},
|
||||
"commandResult": null,
|
||||
"warnings": [],
|
||||
"unavailable": [],
|
||||
"error": null,
|
||||
"exitCode": 0
|
||||
}
|
||||
```
|
||||
|
||||
## LLM And Tooling Commands
|
||||
|
||||
### `capabilities`
|
||||
|
||||
Return the code-backed command registry.
|
||||
|
||||
```powershell
|
||||
graccess capabilities --json
|
||||
graccess capabilities --llm-json
|
||||
```
|
||||
|
||||
The registry includes command names, arguments, mutation status, session routing support, confirmation target rules, and output schema names.
|
||||
|
||||
### `validate`
|
||||
|
||||
Validate a single-command or batch plan file without connecting to GRAccess.
|
||||
|
||||
```powershell
|
||||
graccess validate --request plan.json --llm-json
|
||||
```
|
||||
|
||||
### `batch`
|
||||
|
||||
Validate or execute a command plan. Execution stops on first failure. Every mutating step must include its own `confirm=true` and exact `confirm-target`.
|
||||
|
||||
```powershell
|
||||
graccess batch --file plan.json --mode validate --llm-json
|
||||
graccess batch --file plan.json --mode execute --llm-json
|
||||
```
|
||||
|
||||
Plan example:
|
||||
|
||||
```json
|
||||
{
|
||||
"Galaxy": "ZB",
|
||||
"Node": ".",
|
||||
"Commands": [
|
||||
{
|
||||
"Command": "object attribute value set",
|
||||
"Args": {
|
||||
"name": "TestMachine",
|
||||
"type": "template",
|
||||
"attribute": "Description",
|
||||
"value": "Updated",
|
||||
"data-type": "string",
|
||||
"confirm": true,
|
||||
"confirm-target": "TestMachine"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Galaxy Commands
|
||||
|
||||
### `galaxy list`
|
||||
|
||||
List available galaxies on a GR node.
|
||||
|
||||
```
|
||||
graccess galaxy list [--node <node>] [--json] [--llm-json]
|
||||
```
|
||||
|
||||
| Option | Short | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `--node` | `-n` | No | GR node name to query. Blank defaults to local node; `.` is normalized to the local machine name. |
|
||||
| `--json` | | No | Output as JSON array |
|
||||
| `--llm-json` | | No | Output stable LLM envelope |
|
||||
|
||||
This command always runs in one-shot mode (no galaxy login needed). It does not use or require an active session.
|
||||
|
||||
Example output:
|
||||
```
|
||||
MyGalaxy1
|
||||
MyGalaxy2
|
||||
TestGalaxy
|
||||
```
|
||||
|
||||
With `--json`:
|
||||
```json
|
||||
[
|
||||
"MyGalaxy1",
|
||||
"MyGalaxy2",
|
||||
"TestGalaxy"
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Object Query Commands
|
||||
|
||||
These commands route through an active session when one exists for the target galaxy. Without an active session, they connect to a galaxy, run a read-only GRAccess query, and disconnect. Name patterns use the GRAccess `namedLike` condition; use `%` as the wildcard.
|
||||
|
||||
### `object list`
|
||||
|
||||
List templates, instances, or both.
|
||||
|
||||
```
|
||||
graccess object list --galaxy <name> --node <node> [--type all|template|instance] [--pattern <pattern>] [--json]
|
||||
```
|
||||
|
||||
| Option | Short | Default | Description |
|
||||
|---|---|---|---|
|
||||
| `--galaxy` | `-g` | (required) | Galaxy name |
|
||||
| `--node` | `-n` | local node | GR node name. `.` is normalized to the local machine name. |
|
||||
| `--type` | `-t` | `all` | Object type: `all`, `template`, or `instance` |
|
||||
| `--pattern` | `-p` | `%` | GRAccess name pattern. Use `%` as wildcard. |
|
||||
| `--json` | | `false` | Output as JSON |
|
||||
|
||||
Example:
|
||||
```powershell
|
||||
graccess object list --galaxy ZB --node . --type instance --pattern 'TestMachine_%'
|
||||
```
|
||||
|
||||
### `template list`
|
||||
|
||||
List templates.
|
||||
|
||||
```
|
||||
graccess template list --galaxy <name> --node <node> [--pattern <pattern>] [--json]
|
||||
```
|
||||
|
||||
### `instance list`
|
||||
|
||||
List instances.
|
||||
|
||||
```
|
||||
graccess instance list --galaxy <name> --node <node> [--pattern <pattern>] [--json]
|
||||
```
|
||||
|
||||
Example:
|
||||
```powershell
|
||||
graccess instance list --galaxy ZB --node . --pattern '%'
|
||||
```
|
||||
|
||||
### `object attributes`
|
||||
|
||||
List attributes for a template or instance.
|
||||
|
||||
```
|
||||
graccess object attributes --galaxy <name> --node <node> --name <tagname> [--type all|template|instance] [--configurable] [--json]
|
||||
```
|
||||
|
||||
| Option | Short | Default | Description |
|
||||
|---|---|---|---|
|
||||
| `--galaxy` | `-g` | (required) | Galaxy name |
|
||||
| `--node` | `-n` | local node | GR node name. `.` is normalized to the local machine name. |
|
||||
| `--name` | | (required) | Template or instance tagname |
|
||||
| `--type` | `-t` | `all` | Object type: `all`, `template`, or `instance` |
|
||||
| `--configurable` | | `false` | Query `ConfigurableAttributes` instead of `Attributes` |
|
||||
| `--json` | | `false` | Output as JSON |
|
||||
|
||||
Some optional COM-backed attribute properties are not available for every object. In JSON output those values are emitted as `null`; text output includes the stable name, data type, and category columns.
|
||||
|
||||
Example:
|
||||
```powershell
|
||||
graccess object attributes --galaxy ZB --node . --name DEV --type instance --configurable
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## LLM Snapshot And IDE Commands
|
||||
|
||||
### `object snapshot`
|
||||
|
||||
Return a bundled object snapshot for planning and verification.
|
||||
|
||||
```powershell
|
||||
graccess object snapshot --galaxy ZB --name TestMachine --type template --llm-json
|
||||
```
|
||||
|
||||
Snapshot data includes object identity/status, all attributes, configurable attributes, extended attributes, relationships, lineage, children, contained objects, package-backed attribute values and script bodies where available, and unavailable field details.
|
||||
|
||||
Use snapshots, direct lineage commands, and relationship queries together to parse inheritance and containment:
|
||||
|
||||
```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
|
||||
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
|
||||
```
|
||||
|
||||
`object lineage` walks typed `ITemplate` / `IInstance` relationship properties first and falls back to the read-only package snapshot when GRAccess export is available. `object children` combines package-backed containment with direct GRAccess scans for objects whose `DerivedFrom`, `BasedOn`, `Container`, or `HierarchicalName` point at the target.
|
||||
|
||||
When direct GRAccess does not expose a field, the CLI records a structured unavailable entry instead of guessing. Normal CLI usage does not query the Galaxy SQL database; SQL is allowed only for development verification/debugging outside the supported command path.
|
||||
|
||||
### Attribute values
|
||||
|
||||
```powershell
|
||||
graccess object attribute value get --galaxy ZB --name TestMachine --type template --attribute Description --llm-json
|
||||
graccess object attribute value set --galaxy ZB --name TestMachine --type template --attribute Description --value Updated --data-type string --confirm --confirm-target TestMachine --llm-json
|
||||
```
|
||||
|
||||
Scalar `string`, `bool`, `int`, `float`, and `double` writes are supported first. Value reads try direct `IAttribute.Value` first, then use the read-only exported package fallback for scalar package values. Array and complex readback returns structured unavailable details unless parsed safely.
|
||||
|
||||
### Object scripts
|
||||
|
||||
```powershell
|
||||
graccess object scripts list --galaxy ZB --name TestMachine --type template --llm-json
|
||||
graccess object scripts get --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --llm-json
|
||||
graccess object scripts get --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt.ExecuteText --llm-json
|
||||
graccess object scripts set --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --file UpdateTestChangingInt.txt --confirm --confirm-target TestMachine --llm-json
|
||||
graccess object scripts settings set --galaxy ZB --name '$TestMachine' --type template --script UpdateTestChangingInt --trigger-period-ms 500 --lock-trigger-period --confirm --confirm-target '$TestMachine' --llm-json
|
||||
graccess object scripts create --galaxy ZB --name '$MyTemplate' --type template --script OnScan --file OnScan.txt --trigger-type Periodic --trigger-period-ms 1000 --confirm --confirm-target '$MyTemplate' --llm-json
|
||||
```
|
||||
|
||||
Direct object script body access depends on the local GRAccess object model. Reads inspect the exported package fallback for script extension bodies and script text fields such as `ExecuteText`, `DeclarationsText`, `StartupText`, `ShutdownText`, `OnScanText`, `OffScanText`, and `Expression`.
|
||||
|
||||
For writes, the CLI follows the GRAccess pattern used by `ScriptExtension` objects: script body and setting mutations prefer `IgObject.ConfigurableAttributes[...]`, then fall back to `Attributes[...]` only if the configurable collection does not expose the requested field. `object scripts set` writes the matching script body attribute; a bare script name maps to `.ExecuteText`. `object scripts settings set` writes common script settings such as `TriggerPeriod`, `TriggerType`, and `Expression`; `--lock-trigger-period` applies `MxLockedInMe` so derived instances receive the interval on deploy. `object scripts create` calls `AddExtensionPrimitive("ScriptExtension", <script>, true)` and can initialize the body/settings in the same checkout flow.
|
||||
|
||||
### Area, engine, assignment, and I/O wrappers
|
||||
|
||||
```powershell
|
||||
graccess area list --galaxy ZB --llm-json
|
||||
graccess area create --galaxy ZB --template '$Area' --name Area_Test --confirm --confirm-target '$Area' --llm-json
|
||||
graccess engine list --galaxy ZB --llm-json
|
||||
graccess engine create --galaxy ZB --template '$AppEngine' --name AppEngine_Test --confirm --confirm-target '$AppEngine' --llm-json
|
||||
graccess instance assign-area --galaxy ZB --name TestMachine_001 --area Area_Test --confirm --confirm-target TestMachine_001 --llm-json
|
||||
graccess instance assign-engine --galaxy ZB --name TestMachine_001 --engine AppEngine_Test --confirm --confirm-target TestMachine_001 --llm-json
|
||||
graccess instance assign-container --galaxy ZB --name TestMachine_001 --container ParentObject --confirm --confirm-target TestMachine_001 --llm-json
|
||||
graccess io assign --galaxy ZB --name TestMachine_001 --attribute DeviceAddress --value D100 --confirm --confirm-target TestMachine_001 --llm-json
|
||||
```
|
||||
|
||||
`object set --property area|host|container|toolset|security-group` resolves named GRAccess objects before falling back to string assignment.
|
||||
|
||||
`instance assign-engine` sets the host when the object model accepts a direct engine host. If the instance is already assigned to an area hosted by that engine, the command treats that state as successful because some GRAccess object families use the area as the assignable host.
|
||||
|
||||
### Extending templates and embedded objects
|
||||
|
||||
Use `template derive` to extend an existing template:
|
||||
|
||||
```powershell
|
||||
graccess template derive --galaxy ZB --name '$gMachine' --type template --new-name '$MyMachine' --confirm --confirm-target '$gMachine' --llm-json
|
||||
```
|
||||
|
||||
Use `--create-contained` when deriving or instantiating a template family whose embedded objects should come along:
|
||||
|
||||
```powershell
|
||||
graccess template derive --galaxy ZB --name '$TestMachine' --type template --new-name '$MyMachine' --create-contained --confirm --confirm-target '$TestMachine' --llm-json
|
||||
graccess template instantiate --galaxy ZB --name '$TestMachine' --type template --new-name TestMachine_021 --create-contained --confirm --confirm-target '$TestMachine' --llm-json
|
||||
```
|
||||
|
||||
`template delete --force-option` defaults to `dontForceTemplateDelete`, which fails when instances exist instead of cascading. `instance delete --force-option` defaults to `undeployIfDeployed` so cleanup can remove deployed test instances after confirmation. `object uda add` and `object uda update` default `--category` to `MxCategoryWriteable_USC`; GRAccess builds that reject non-lockable UDA categories are normalized to `MxCategoryWriteable_USC_Lockable` at the COM call. Pass another valid `MxAttributeCategory` explicitly when a configure-only or calculated category is required. `object extension add/delete` pass typed extension calls to GRAccess; the legacy `AnalogLimitAlarm` extension type is accepted as an alias for the local `AnalogExtension` primitive type.
|
||||
|
||||
Single-object UDA, extension, attribute, script, and I/O mutations are atomic: the CLI checks out the object, applies the mutation, saves, and checks it back in. If the mutation or save fails after checkout, the CLI attempts `UndoCheckOut` before returning the original error. The explicit `object checkout/save/checkin` and `objects checkout/checkin` commands remain available for manual lifecycle operations.
|
||||
|
||||
Contained templates and child instances are edited as normal objects by targeting their own tagname:
|
||||
|
||||
```powershell
|
||||
graccess object snapshot --galaxy ZB --name '$TestMachine.DelmiaReceiver' --type template --llm-json
|
||||
graccess object snapshot --galaxy ZB --name DelmiaReceiver_001 --type instance --llm-json
|
||||
graccess object checkout --galaxy ZB --name DelmiaReceiver_001 --type instance --confirm --confirm-target DelmiaReceiver_001
|
||||
graccess object attribute value set --galaxy ZB --name DelmiaReceiver_001 --type instance --attribute DownloadPath --value 'C:\Recipes\001' --data-type string --confirm --confirm-target DelmiaReceiver_001 --llm-json
|
||||
graccess object save --galaxy ZB --name DelmiaReceiver_001 --type instance --confirm --confirm-target DelmiaReceiver_001
|
||||
graccess object checkin --galaxy ZB --name DelmiaReceiver_001 --type instance --comment 'Configure embedded receiver' --confirm --confirm-target DelmiaReceiver_001
|
||||
```
|
||||
|
||||
Use `instance assign-container` or `object set --property container` only after confirming the object model allows moving/reparenting that child.
|
||||
|
||||
---
|
||||
|
||||
## Session Management
|
||||
|
||||
Session mode keeps a GRAccess connection open in a background daemon process, avoiding expensive reconnection on each CLI invocation.
|
||||
|
||||
### `session start`
|
||||
|
||||
Start a background session for a galaxy.
|
||||
|
||||
```
|
||||
graccess session start --galaxy <name> --node <node> [--idle-timeout <minutes>]
|
||||
```
|
||||
|
||||
| Option | Default | Description |
|
||||
|---|---|---|
|
||||
| `--galaxy`, `-g` | (required) | Galaxy name |
|
||||
| `--node`, `-n` | (required) | GR node name. `.` is normalized to the local machine name. |
|
||||
| `--idle-timeout` | 30 | Minutes of inactivity before auto-shutdown |
|
||||
|
||||
Behavior:
|
||||
- Spawns a background daemon process
|
||||
- Waits up to 90 seconds for the daemon to connect and become ready
|
||||
- If a session is already running for this galaxy, reports the existing PID
|
||||
- Daemon logs to `%LOCALAPPDATA%\ZB.MOM.WW.GRAccess.Cli\logs\daemon-{galaxy}.log`
|
||||
|
||||
### `session stop`
|
||||
|
||||
Stop a running session.
|
||||
|
||||
```
|
||||
graccess session stop --galaxy <name>
|
||||
```
|
||||
|
||||
Sends a shutdown signal to the daemon via named pipe. The daemon disconnects from the galaxy and exits.
|
||||
|
||||
### `session status`
|
||||
|
||||
Check if a session is running.
|
||||
|
||||
```
|
||||
graccess session status --galaxy <name>
|
||||
```
|
||||
|
||||
Output includes: galaxy name, node, PID, start time, and pipe name. Automatically cleans up stale session files from crashed daemons.
|
||||
|
||||
## Execution Modes
|
||||
|
||||
### Session mode (fast)
|
||||
|
||||
When a session is active, commands route through the daemon automatically:
|
||||
|
||||
```bash
|
||||
graccess session start --galaxy MyGalaxy --node MyNode
|
||||
graccess <command> --galaxy MyGalaxy [options] # routed via named pipe
|
||||
graccess <command> --galaxy MyGalaxy [options] # reuses same connection
|
||||
graccess session stop --galaxy MyGalaxy
|
||||
```
|
||||
|
||||
### One-shot mode (no session)
|
||||
|
||||
Without an active session, commands open a direct connection, execute, and disconnect:
|
||||
|
||||
```bash
|
||||
graccess <command> --galaxy MyGalaxy --node MyNode [options]
|
||||
```
|
||||
|
||||
This is slower but requires no setup. The `--node` option is required in one-shot mode.
|
||||
|
||||
### Routing logic
|
||||
|
||||
The `CommandRouter` checks for an active session first:
|
||||
1. Look up session info file at `%LOCALAPPDATA%\ZB.MOM.WW.GRAccess.Cli\sessions\{galaxy}.json`
|
||||
2. Verify the daemon process is alive (PID check)
|
||||
3. If alive, send command as JSON via named pipe `graccess-session-{galaxy}`
|
||||
4. If no session, fall back to one-shot mode (requires `--node`)
|
||||
|
||||
Currently routed through the session daemon:
|
||||
- `object list`
|
||||
- `template list`
|
||||
- `instance list`
|
||||
- `object attributes`
|
||||
- All other logged-in galaxy commands added under `galaxy`, `object`, `template`, `instance`, `objects`, `toolset`, `script-library`, `security`, and `settings`.
|
||||
|
||||
Pre-login galaxy administration commands remain one-shot because they operate before a galaxy session exists:
|
||||
- `galaxy list`
|
||||
- `galaxy create`
|
||||
- `galaxy create-from-template`
|
||||
- `galaxy delete`
|
||||
|
||||
## Expanded Command Surface
|
||||
|
||||
The CLI exposes the GRAccess operations listed in `graccess_operations.md` through these command families:
|
||||
|
||||
| Family | Commands |
|
||||
|---|---|
|
||||
| Galaxy | `galaxy info`, `galaxy sync`, `galaxy cdi-version`, `galaxy defaults get/set`, `galaxy backup/restore/migrate`, `galaxy import-objects`, `galaxy import-objects-ex`, `galaxy import-script-library`, `galaxy export-all`, `galaxy grload`, `galaxy create`, `galaxy create-from-template`, `galaxy delete` |
|
||||
| Objects | `object get`, `object snapshot`, `object lineage`, `object children`, `object query-name`, `object query-condition`, `object query-multi`, `object extended-attributes`, `object help-url`, `object scripts list/get/set`, `object checkout/checkin/undo-checkout/save/unload/set` |
|
||||
| Templates and instances | `template derive`, `template instantiate`, `template delete`, `instance delete/deploy/undeploy/upload`, `instance assign-area/assign-engine/assign-container` |
|
||||
| Attributes, UDAs, extensions | `object attribute get/set/value get/value set/lock/security/buffer`, `object uda add/delete/rename/update`, `object extension add/delete/rename` |
|
||||
| Bulk objects | `objects checkout/checkin/undo-checkout/deploy/undeploy/upload/delete/export/export-protected` |
|
||||
| IDE wrappers and tooling | `capabilities`, `validate`, `batch`, `area list/create`, `engine list/create`, `io assign` |
|
||||
| Toolsets/scripts/security/settings | `toolset list/tree/add/delete/rename/move`, `script-library list/add/import/export`, `security info/roles/users/groups/permissions`, `settings locale get`, `settings time-master get` |
|
||||
|
||||
Mutating commands require `--confirm`. Mutating commands also validate `--confirm-target` against the exact object, galaxy, bulk target list, or file target used by the command.
|
||||
|
||||
## IPC Protocol
|
||||
|
||||
Communication between CLI and daemon uses newline-delimited JSON over named pipes.
|
||||
|
||||
### Request format
|
||||
|
||||
```json
|
||||
{"type":"execute","command":"<cmd>","subcommand":"<subcmd>","args":{"key":"value"}}
|
||||
```
|
||||
|
||||
Request types: `execute`, `shutdown`, `status`
|
||||
|
||||
### Response format
|
||||
|
||||
```json
|
||||
{"success":true,"output":"...","exitCode":0}
|
||||
{"success":false,"error":"...","exitCode":1}
|
||||
```
|
||||
|
||||
## Daemon Details
|
||||
|
||||
- **Pipe name**: `graccess-session-{galaxyname}` (lowercase)
|
||||
- **Mutex**: `Global\graccess-session-{galaxyname}` (prevents duplicate daemons per galaxy)
|
||||
- **Session file**: `%LOCALAPPDATA%\ZB.MOM.WW.GRAccess.Cli\sessions\{galaxy}.json`
|
||||
- **Log file**: `%LOCALAPPDATA%\ZB.MOM.WW.GRAccess.Cli\logs\daemon-{galaxy}.log` (daily rolling, 7 day retention)
|
||||
- **Idle timeout**: Checked every 30 seconds; daemon self-exits when exceeded
|
||||
- **COM threading**: All GRAccess calls run on a dedicated STA thread with a Win32 message pump (`StaComThread`)
|
||||
@@ -0,0 +1,156 @@
|
||||
# ZB Galaxy Documentation
|
||||
|
||||
Captured read-only with `graccess_cli` on 2026-04-28 through a session daemon:
|
||||
|
||||
```powershell
|
||||
graccess session start --galaxy ZB --node .
|
||||
graccess galaxy info --galaxy ZB --llm-json
|
||||
graccess template list --galaxy ZB --pattern '%' --llm-json
|
||||
graccess instance list --galaxy ZB --pattern '%' --llm-json
|
||||
graccess security info --galaxy ZB --llm-json
|
||||
graccess settings time-master get --galaxy ZB --llm-json
|
||||
```
|
||||
|
||||
Session observed during capture:
|
||||
|
||||
- Galaxy: `ZB`
|
||||
- Node: `DESKTOP-6JL3KKO`
|
||||
- Pipe: `graccess-session-zb`
|
||||
|
||||
## Galaxy Identity
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Name | `ZB` |
|
||||
| System Platform version string | `20.0.00000` |
|
||||
| Version number | `43` |
|
||||
| Upgrade required | `false` |
|
||||
| CDI version | `5800.0474.7005.1` |
|
||||
|
||||
## Inventory Summary
|
||||
|
||||
| Object class | Count | Notes |
|
||||
| --- | ---: | --- |
|
||||
| Templates | 45 | Includes base System Platform templates, master templates, and project templates. |
|
||||
| Instances | 67 | Includes 60 objects in the `TestMachine` family plus 7 standalone/development objects. |
|
||||
| Toolsets | 0 | `toolset list` returned an empty array through the CLI. |
|
||||
| Script libraries | 0 | `script-library list` returned an empty array through the CLI. |
|
||||
| Security roles | 0 | `security roles` returned an empty array. |
|
||||
| Security users | 0 | `security users` returned an empty array. |
|
||||
| Security groups | 0 | `security groups` returned an empty array. |
|
||||
|
||||
`area list` and `engine list` returned empty arrays with their default patterns, but the raw instance inventory includes objects that look like development platform/engine/area objects: `DevPlatform`, `DevAppEngine`, `TestArea`, and `TestArea2`. Treat the typed wrapper results as the current CLI view, not proof that no platform or area-like objects exist in the galaxy.
|
||||
|
||||
## Templates
|
||||
|
||||
The galaxy has 45 templates:
|
||||
|
||||
| Template | Contained name | Checkout |
|
||||
| --- | --- | --- |
|
||||
| `$AnalogDevice` | | `notCheckedOut` |
|
||||
| `$AppEngine` | | `notCheckedOut` |
|
||||
| `$Area` | | `notCheckedOut` |
|
||||
| `$DDESuiteLinkClient` | | `notCheckedOut` |
|
||||
| `$DelmiaReceiver` | | `notCheckedOut` |
|
||||
| `$DiscreteDevice` | | `notCheckedOut` |
|
||||
| `$gAppEngine` | | `notCheckedOut` |
|
||||
| `$gArea` | | `notCheckedOut` |
|
||||
| `$gDDESuiteLinkClient` | | `notCheckedOut` |
|
||||
| `$gMachine` | | `notCheckedOut` |
|
||||
| `$gUserDefined` | | `notCheckedOut` |
|
||||
| `$gViewEngine` | | `notCheckedOut` |
|
||||
| `$gWinPlatform` | | `notCheckedOut` |
|
||||
| `$InTouchOMI_ViewApp` | | `notCheckedOut` |
|
||||
| `$InTouchProxy` | | `notCheckedOut` |
|
||||
| `$InTouchViewApp` | | `notCheckedOut` |
|
||||
| `$Master_AnalogDevice` | | `notCheckedOut` |
|
||||
| `$Master_AppEngine` | | `notCheckedOut` |
|
||||
| `$Master_Area` | | `notCheckedOut` |
|
||||
| `$Master_DDESuiteLinkClient` | | `notCheckedOut` |
|
||||
| `$Master_DiscreteDevice` | | `notCheckedOut` |
|
||||
| `$Master_InTouchProxy` | | `notCheckedOut` |
|
||||
| `$Master_OPCClient` | | `notCheckedOut` |
|
||||
| `$Master_RedundantDIObject` | | `notCheckedOut` |
|
||||
| `$Master_Sequencer` | | `notCheckedOut` |
|
||||
| `$Master_SQLData` | | `notCheckedOut` |
|
||||
| `$Master_UserDefined` | | `notCheckedOut` |
|
||||
| `$Master_ViewEngine` | | `notCheckedOut` |
|
||||
| `$Master_WinPlatform` | | `notCheckedOut` |
|
||||
| `$MESReceiver` | | `notCheckedOut` |
|
||||
| `$OIGW` | | `notCheckedOut` |
|
||||
| `$OPCClient` | | `notCheckedOut` |
|
||||
| `$RedundantDIObject` | | `notCheckedOut` |
|
||||
| `$Sequencer` | | `notCheckedOut` |
|
||||
| `$Sim` | | `notCheckedOut` |
|
||||
| `$SQLData` | | `notCheckedOut` |
|
||||
| `$TestMachine` | | `checkedOutToMe` |
|
||||
| `$TestMachine.DelmiaReceiver` | `DelmiaReceiver` | `notCheckedOut` |
|
||||
| `$TestMachine.MESReceiver` | `MESReceiver` | `notCheckedOut` |
|
||||
| `$TestObject` | | `notCheckedOut` |
|
||||
| `$TestObject.TestChildObject` | `TestChildObject` | `notCheckedOut` |
|
||||
| `$UserDefined` | | `notCheckedOut` |
|
||||
| `$ViewApp` | | `notCheckedOut` |
|
||||
| `$ViewEngine` | | `notCheckedOut` |
|
||||
| `$WinPlatform` | | `notCheckedOut` |
|
||||
|
||||
## Instances
|
||||
|
||||
The instance inventory has 67 objects. Grouped by contained name:
|
||||
|
||||
| Contained name | Count | Meaning |
|
||||
| --- | ---: | --- |
|
||||
| empty | 24 | 20 `TestMachine_*` parent instances plus `DEV`, `DevAppEngine`, `DevPlatform`, and `DevTestObject`. |
|
||||
| `DelmiaReceiver` | 20 | One contained receiver under each `TestMachine_001` through `TestMachine_020`. |
|
||||
| `MESReceiver` | 20 | One contained MES receiver under each `TestMachine_001` through `TestMachine_020`. |
|
||||
| `TestArea` | 1 | Contained under `DEV`. |
|
||||
| `TestArea2` | 1 | Contained under `DEV`. |
|
||||
| `TestChildObject` | 1 | Contained under `DevTestObject`. |
|
||||
|
||||
The `TestMachine` instance family is the dominant application model in this galaxy:
|
||||
|
||||
| Parent | Delmia child | MES child |
|
||||
| --- | --- | --- |
|
||||
| `TestMachine_001` | `TestMachine_001.DelmiaReceiver` / `DelmiaReceiver_001` | `TestMachine_001.MESReceiver` / `MESReceiver_001` |
|
||||
| `TestMachine_002` | `TestMachine_002.DelmiaReceiver` / `DelmiaReceiver_002` | `TestMachine_002.MESReceiver` / `MESReceiver_002` |
|
||||
| `TestMachine_003` | `TestMachine_003.DelmiaReceiver` / `DelmiaReceiver_003` | `TestMachine_003.MESReceiver` / `MESReceiver_003` |
|
||||
| `TestMachine_004` | `TestMachine_004.DelmiaReceiver` / `DelmiaReceiver_004` | `TestMachine_004.MESReceiver` / `MESReceiver_004` |
|
||||
| `TestMachine_005` | `TestMachine_005.DelmiaReceiver` / `DelmiaReceiver_005` | `TestMachine_005.MESReceiver` / `MESReceiver_005` |
|
||||
| `TestMachine_006` | `TestMachine_006.DelmiaReceiver` / `DelmiaReceiver_006` | `TestMachine_006.MESReceiver` / `MESReceiver_006` |
|
||||
| `TestMachine_007` | `TestMachine_007.DelmiaReceiver` / `DelmiaReceiver_007` | `TestMachine_007.MESReceiver` / `MESReceiver_007` |
|
||||
| `TestMachine_008` | `TestMachine_008.DelmiaReceiver` / `DelmiaReceiver_008` | `TestMachine_008.MESReceiver` / `MESReceiver_008` |
|
||||
| `TestMachine_009` | `TestMachine_009.DelmiaReceiver` / `DelmiaReceiver_009` | `TestMachine_009.MESReceiver` / `MESReceiver_009` |
|
||||
| `TestMachine_010` | `TestMachine_010.DelmiaReceiver` / `DelmiaReceiver_010` | `TestMachine_010.MESReceiver` / `MESReceiver_010` |
|
||||
| `TestMachine_011` | `TestMachine_011.DelmiaReceiver` / `DelmiaReceiver_011` | `TestMachine_011.MESReceiver` / `MESReceiver_011` |
|
||||
| `TestMachine_012` | `TestMachine_012.DelmiaReceiver` / `DelmiaReceiver_012` | `TestMachine_012.MESReceiver` / `MESReceiver_012` |
|
||||
| `TestMachine_013` | `TestMachine_013.DelmiaReceiver` / `DelmiaReceiver_013` | `TestMachine_013.MESReceiver` / `MESReceiver_013` |
|
||||
| `TestMachine_014` | `TestMachine_014.DelmiaReceiver` / `DelmiaReceiver_014` | `TestMachine_014.MESReceiver` / `MESReceiver_014` |
|
||||
| `TestMachine_015` | `TestMachine_015.DelmiaReceiver` / `DelmiaReceiver_015` | `TestMachine_015.MESReceiver` / `MESReceiver_015` |
|
||||
| `TestMachine_016` | `TestMachine_016.DelmiaReceiver` / `DelmiaReceiver_016` | `TestMachine_016.MESReceiver` / `MESReceiver_016` |
|
||||
| `TestMachine_017` | `TestMachine_017.DelmiaReceiver` / `DelmiaReceiver_017` | `TestMachine_017.MESReceiver` / `MESReceiver_017` |
|
||||
| `TestMachine_018` | `TestMachine_018.DelmiaReceiver` / `DelmiaReceiver_018` | `TestMachine_018.MESReceiver` / `MESReceiver_018` |
|
||||
| `TestMachine_019` | `TestMachine_019.DelmiaReceiver` / `DelmiaReceiver_019` | `TestMachine_019.MESReceiver` / `MESReceiver_019` |
|
||||
| `TestMachine_020` | `TestMachine_020.DelmiaReceiver` / `DelmiaReceiver_020` | `TestMachine_020.MESReceiver` / `MESReceiver_020` |
|
||||
|
||||
All listed instances were `notCheckedOut` during capture.
|
||||
|
||||
## Security
|
||||
|
||||
`security info` returned:
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Authentication mode | `eNone` |
|
||||
| Login time | `1000` |
|
||||
| Role update interval | `0` |
|
||||
|
||||
The role, user, and group collections returned empty arrays through the CLI.
|
||||
|
||||
## Settings And Read Limitations
|
||||
|
||||
| Read | Result |
|
||||
| --- | --- |
|
||||
| `settings time-master get` | Success, `Instance` was empty. |
|
||||
| `settings locale get` | Failed with `COMException`: `Exception from HRESULT: 0xC0000005`. |
|
||||
| `galaxy cdi-version` | Success, `5800.0474.7005.1`. |
|
||||
|
||||
Treat failed or empty settings reads as observed CLI/GRAccess results, not necessarily as authoritative absence in the IDE. The local GRAccess COM layer can fail specific property reads while other object queries continue to work.
|
||||
@@ -0,0 +1,320 @@
|
||||
# ZB TestMachine Template And Instance Documentation
|
||||
|
||||
Captured read-only from galaxy `ZB` on 2026-04-28 with `graccess_cli --llm-json`.
|
||||
|
||||
Core commands used:
|
||||
|
||||
```powershell
|
||||
graccess template list --galaxy ZB --pattern '%TestMachine%' --llm-json
|
||||
graccess instance list --galaxy ZB --pattern '%TestMachine%' --llm-json
|
||||
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
|
||||
graccess object snapshot --galaxy ZB --name '$TestMachine.DelmiaReceiver' --type template --llm-json
|
||||
graccess object snapshot --galaxy ZB --name '$TestMachine.MESReceiver' --type template --llm-json
|
||||
graccess object snapshot --galaxy ZB --name TestMachine_001 --type instance --llm-json
|
||||
graccess object snapshot --galaxy ZB --name DelmiaReceiver_001 --type instance --llm-json
|
||||
graccess object snapshot --galaxy ZB --name MESReceiver_001 --type instance --llm-json
|
||||
```
|
||||
|
||||
## Object Family
|
||||
|
||||
`$TestMachine` is a parent template derived from the System Platform `$gMachine` base template. Older captures had blank generic `DerivedFrom` / `BasedOn` fields; newer CLI builds should prefer `object lineage` and `object children` because they use typed GRAccess relationship reads and package fallback where available. The intended IDE inheritance for this object is:
|
||||
|
||||
```text
|
||||
$gMachine
|
||||
-> $TestMachine
|
||||
-> $TestMachine.DelmiaReceiver
|
||||
-> $TestMachine.MESReceiver
|
||||
```
|
||||
|
||||
`$TestMachine.DelmiaReceiver` and `$TestMachine.MESReceiver` are contained embedded templates under `$TestMachine`, not standalone peer templates in the runtime hierarchy. They become contained child objects when a `TestMachine_*` parent instance is instantiated with contained-object creation enabled.
|
||||
|
||||
| Object | Relationship | Notes |
|
||||
| --- | --- | --- |
|
||||
| `$gMachine` | Base template | System Platform machine template extended by `$TestMachine`. |
|
||||
| `$TestMachine` | Derived template | Adds machine identity, test alarm, historized value, array, protected-value, and script families. |
|
||||
| `$TestMachine.DelmiaReceiver` | Contained template | Embedded receiver template with recipe/download attributes and `ProcessRecipe` / `Reset` script families. |
|
||||
| `$TestMachine.MESReceiver` | Contained template | Embedded receiver template with MES move-in/move-out attributes. |
|
||||
|
||||
The family contains two child templates:
|
||||
|
||||
| Template | Contained name | Checkout status |
|
||||
| --- | --- | --- |
|
||||
| `$TestMachine` | | `checkedOutToMe` |
|
||||
| `$TestMachine.DelmiaReceiver` | `DelmiaReceiver` | `notCheckedOut` |
|
||||
| `$TestMachine.MESReceiver` | `MESReceiver` | `notCheckedOut` |
|
||||
|
||||
There are 20 parent instances, each with one `DelmiaReceiver` child and one `MESReceiver` child.
|
||||
|
||||
| Parent instance range | Child ranges |
|
||||
| --- | --- |
|
||||
| `TestMachine_001` through `TestMachine_020` | `DelmiaReceiver_001` through `DelmiaReceiver_020`; `MESReceiver_001` through `MESReceiver_020` |
|
||||
|
||||
The child instances use contained hierarchical names, for example:
|
||||
|
||||
- `DelmiaReceiver_001` has hierarchical name `TestMachine_001.DelmiaReceiver`.
|
||||
- `MESReceiver_001` has hierarchical name `TestMachine_001.MESReceiver`.
|
||||
|
||||
For future CLI captures, parse inheritance with lineage, children, snapshot fields, and relationship queries:
|
||||
|
||||
```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
|
||||
graccess object query-condition --galaxy ZB --type all --condition basedOn --value '$gMachine' --llm-json
|
||||
graccess object query-condition --galaxy ZB --type all --condition derivedOrInstantiatedFrom --value '$gMachine' --llm-json
|
||||
```
|
||||
|
||||
During the original capture, the two relationship queries returned empty arrays through the generic query path, so `$TestMachine -> $gMachine` was verified separately as IDE/SQL verification evidence. Normal CLI usage must not depend on SQL; SQL is only a development verification/debugging oracle.
|
||||
|
||||
## Snapshot Summary
|
||||
|
||||
| Object | Kind | Attributes | Configurable attributes | Script-like entries | Unavailable fields |
|
||||
| --- | --- | ---: | ---: | ---: | ---: |
|
||||
| `$TestMachine` | template | 282 | 282 | 22 | 0 |
|
||||
| `$TestMachine.DelmiaReceiver` | template | 178 | 178 | 36 | 1 |
|
||||
| `$TestMachine.MESReceiver` | template | 110 | 110 | 25 | 1 |
|
||||
| `TestMachine_001` | instance | 282 | 282 | 22 | 0 |
|
||||
| `DelmiaReceiver_001` | instance | 179 | 179 | 36 | 1 |
|
||||
| `MESReceiver_001` | instance | 110 | 110 | 25 | 1 |
|
||||
|
||||
Earlier snapshots reported package/export fallback failures with:
|
||||
|
||||
```text
|
||||
Library not registered. (Exception from HRESULT: 0x8002801D (TYPE_E_LIBNOTREGISTERED))
|
||||
```
|
||||
|
||||
That was traced to .NET publisher-policy binding to the GAC `ArchestrA.GRAccess` 2.0 interop assembly plus late-bound reflection on `IgObjects.ExportObjects`. Current CLI builds disable that publisher policy and use typed `IgObjects` export calls. `object snapshot --llm-json` now reaches package fallback without a `TYPE_E_LIBNOTREGISTERED` unavailable entry.
|
||||
|
||||
Script metadata is readable. Direct script body readback is still not exposed through the generic local GRAccess value path, but the CLI now parses nested exported package archives and binary UTF-16 `ScriptExtension` records. `object scripts get --script UpdateTestChangingInt` and `--script UpdateTestChangingInt.ExecuteText` return the package-backed body:
|
||||
|
||||
```text
|
||||
Me.TestChangingInt = System.Random().Next(1,1000);
|
||||
```
|
||||
|
||||
## `$TestMachine` Attribute Structure
|
||||
|
||||
The base template has 282 attributes. Category distribution:
|
||||
|
||||
| Category | Count |
|
||||
| --- | ---: |
|
||||
| `MxCategoryCalculated` | 65 |
|
||||
| `MxCategoryWriteable_USC_Lockable` | 46 |
|
||||
| `MxCategoryPackageOnly` | 29 |
|
||||
| `MxCategoryCalculatedRetentive` | 27 |
|
||||
| `MxCategoryWriteable_C_Lockable` | 25 |
|
||||
| `MxCategory_SystemInternal` | 22 |
|
||||
| `MxCategoryPackageOnly_Lockable` | 22 |
|
||||
| `MxCategoryWriteable_US` | 15 |
|
||||
| `MxCategory_Constant` | 13 |
|
||||
| `MxCategory_SystemWriteable` | 7 |
|
||||
|
||||
Data type distribution:
|
||||
|
||||
| Data type | Count |
|
||||
| --- | ---: |
|
||||
| `MxString` | 87 |
|
||||
| `MxBoolean` | 63 |
|
||||
| `MxInteger` | 37 |
|
||||
| `MxQualifiedEnum` | 22 |
|
||||
| `MxBigString` | 18 |
|
||||
| `MxTime` | 17 |
|
||||
| `MxQualifiedStruct` | 9 |
|
||||
| `MxReferenceType` | 9 |
|
||||
| `MxDataTypeEnum` | 7 |
|
||||
| `MxFloat` | 5 |
|
||||
| `MxElapsedTime` | 4 |
|
||||
| `MxInternationalizedString` | 2 |
|
||||
| `MxDouble` | 1 |
|
||||
| `MxStatusType` | 1 |
|
||||
|
||||
Security classification distribution:
|
||||
|
||||
| Security classification | Count |
|
||||
| --- | ---: |
|
||||
| `MxSecurityUndefined` | 192 |
|
||||
| `MxSecurityOperate` | 28 |
|
||||
| `MxSecurityFreeAccess` | 24 |
|
||||
| `MxSecurityViewOnly` | 18 |
|
||||
| `MxSecurityTune` | 12 |
|
||||
| `MxSecurityConfigure` | 6 |
|
||||
| `MxSecuritySecuredWrite` | 1 |
|
||||
| `MxSecurityVerifiedWrite` | 1 |
|
||||
|
||||
## `$TestMachine` Top-Level User Attributes
|
||||
|
||||
| Attribute | Data type | Category | Security | Lock |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `MachineCode` | `MxString` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` | `MxUnLocked` |
|
||||
| `MachineDescription` | `MxString` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` | `MxUnLocked` |
|
||||
| `MachineID` | `MxString` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` | `MxUnLocked` |
|
||||
| `TestAlarm001` | `MxBoolean` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` | `MxUnLocked` |
|
||||
| `TestAlarm002` | `MxBoolean` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` | `MxUnLocked` |
|
||||
| `TestAlarm003` | `MxBoolean` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` | `MxUnLocked` |
|
||||
| `ProtectedValue` | `MxBoolean` | `MxCategoryWriteable_USC_Lockable` | `MxSecuritySecuredWrite` | `MxUnLocked` |
|
||||
| `ProtectedValue1` | `MxBoolean` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityVerifiedWrite` | `MxUnLocked` |
|
||||
| `TestHistoryValue` | `MxInteger` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` | `MxUnLocked` |
|
||||
| `TestStringArray` | `MxString` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` | `MxUnLocked` |
|
||||
| `TestIntArray` | `MxInteger` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` | `MxUnLocked` |
|
||||
| `TestDateTimeArray` | `MxTime` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` | `MxUnLocked` |
|
||||
| `TestBoolArray` | `MxBoolean` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` | `MxUnLocked` |
|
||||
| `TestChangingInt` | `MxInteger` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` | `MxUnLocked` |
|
||||
|
||||
The CLI also read normal framework top-level attributes such as `Tagname`, `ShortDesc`, `ScanStateCmd`, `SecurityGroup`, `Area`, `Container`, `Host`, `ConfigVersion`, `ExecutionRelatedObject`, `ExecutionRelativeOrder`, `ContainedName`, and `HierarchicalName`.
|
||||
|
||||
Scalar value readback for the user attributes returned "not exposed by this GRAccess attribute" through the current generic value path. Use snapshots for metadata and use export/version-specific adapters when exact IDE-entered values are required.
|
||||
|
||||
## `$TestMachine` Attribute Families
|
||||
|
||||
Dot-child groups found in the base template:
|
||||
|
||||
| Root | Child attribute count | Purpose |
|
||||
| --- | ---: | --- |
|
||||
| `MachineCode` | 1 | Description metadata. |
|
||||
| `MachineDescription` | 1 | Description metadata. |
|
||||
| `MachineID` | 1 | Description metadata. |
|
||||
| `TestAlarm001` | 45 | Alarm extension/settings family. |
|
||||
| `TestAlarm002` | 45 | Alarm extension/settings family. |
|
||||
| `TestAlarm003` | 45 | Alarm extension/settings family. |
|
||||
| `TestHistoryValue` | 19 | Historization/settings family. |
|
||||
| `UpdateTestChangingInt` | 47 | Script object/settings family. |
|
||||
|
||||
Alarm families for `TestAlarm001`, `TestAlarm002`, and `TestAlarm003` include:
|
||||
|
||||
- Identity and extension metadata: `_ExternalName`, `_InternalName`, `HasStatistics`, `_RefAttrID`, `_ExtensionAttributeDatatypes`, `_ExtensionAttributeCategories`.
|
||||
- Aggregate status: `AlarmMostUrgentSeverity`, `AlarmMostUrgentMode`, `AlarmMostUrgentAcked`, `AlarmCntsBySeverity`, `AlarmMostUrgentInAlarm`, `AlarmMostUrgentShelved`.
|
||||
- Runtime status: `InAlarm`, `TimeAlarmOn`, `TimeAlarmOff`, `TimeAlarmAcked`, `Acked`.
|
||||
- Operator/configuration settings: `Priority`, `Category`, `AckMsg`, `DescAttrName`, `ActiveAlarmState`, `AlarmMode`, `AlarmModeCmd`, `AlarmInhibit`.
|
||||
- Shelving settings: `AlarmShelveCmd`, `AlarmShelved`, `AlarmShelveStartTime`, `AlarmShelveStopTime`, `AlarmShelveReason`, `AlarmShelveUser`, `AlarmShelveNode`.
|
||||
- Condition/source settings: `Alarm.TimeDeadband`, `Condition`, `ConditionCached`, `AlarmSourceAttr`.
|
||||
|
||||
The `TestHistoryValue` history family includes:
|
||||
|
||||
- Identity metadata: `_ExternalName`, `_InternalName`, `_key`, `_refHistAttrKey`, `_ExtensionAttributeDatatypes`, `_ExtensionAttributeCategories`.
|
||||
- Storage behavior: `ValueDeadBand`, `ForceStoragePeriod`, `InterpolationType`, `RolloverValue`, `SampleCount`, `EnableSwingingDoor`, `RateDeadBand`.
|
||||
- Display/range metadata: `TrendHi`, `TrendLo`, `EngUnits`, `Hist.DescAttrName`.
|
||||
|
||||
The `UpdateTestChangingInt` script family includes:
|
||||
|
||||
- Script text fields: `ExecuteText`, `DeclarationsText`, `StartupText`, `ShutdownText`, `OnScanText`, `OffScanText`, `Expression`.
|
||||
- Package-backed `ExecuteText` body: `Me.TestChangingInt = System.Random().Next(1,1000);`.
|
||||
- Trigger/execution settings: `TriggerType`, `TriggerPeriod`, `TriggerOnQualityChange`, `DataChangeDeadband`, `RunsAsync`, `ExecuteTimeout.Limit`, `AsyncShutdownCmd`.
|
||||
- Runtime statistics/status: `StatsReset`, `ErrorCnt`, `ExecutionCnt`, `ExecutionTime`, `ExecutionTimeAvg`, `ExecutionTimeStamp`, `Disabled`, `State`, `_LastExpression`.
|
||||
- Dependency/reference metadata: `AliasReferences`, `Aliases`, `_ExternalReferences`, `_ExternalReferenceFlags`, `_AliasReferenceFlags`, `_Guid`, `_LibraryDependencies`.
|
||||
- Error metadata: `ExecutionError.Condition`, `ExecutionError.Alarmed`, `ExecutionError.Desc`, `_ErrorMessage`, `_ErrorLine`, `_ErrorColumn`, `_ErrorReport`.
|
||||
- Ordering/group metadata: `ScriptExecutionGroup`, `ScriptOrder`, `_ScriptExecutionGroupEnum`.
|
||||
|
||||
## `$TestMachine.DelmiaReceiver`
|
||||
|
||||
This contained template has 178 attributes and 36 script-like metadata entries.
|
||||
|
||||
Main user attributes:
|
||||
|
||||
| Attribute | Data type | Category | Security |
|
||||
| --- | --- | --- | --- |
|
||||
| `DownloadPath` | `MxString` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` |
|
||||
| `JobStepNumber` | `MxString` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` |
|
||||
| `PartNumber` | `MxString` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` |
|
||||
| `ReadyFlag` | `MxBoolean` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` |
|
||||
| `RecipeDownloadFlag` | `MxBoolean` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` |
|
||||
| `RecipeProcessedFlag` | `MxBoolean` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` |
|
||||
| `RecipeProcessResult` | `MxBoolean` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` |
|
||||
| `RecipeProcessResultText` | `MxString` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` |
|
||||
| `Username` | `MxString` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` |
|
||||
| `WorkOrderNumber` | `MxString` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` |
|
||||
|
||||
Script families:
|
||||
|
||||
| Root | Child count | Notable fields |
|
||||
| --- | ---: | --- |
|
||||
| `ProcessRecipe` | 47 | `ExecuteText`, `Expression`, startup/shutdown/on-scan/off-scan text, trigger settings, execution stats, timeout, async shutdown. |
|
||||
| `Reset` | 47 | Same script/settings pattern as `ProcessRecipe`. |
|
||||
|
||||
## `$TestMachine.MESReceiver`
|
||||
|
||||
This contained template has 110 attributes and 25 script-like metadata entries.
|
||||
|
||||
Main user attributes:
|
||||
|
||||
| Attribute | Data type |
|
||||
| --- | --- |
|
||||
| `MoveInBatchID` | `MxInteger` |
|
||||
| `MoveInCompleteFlag` | `MxInteger` |
|
||||
| `MoveInErrorText` | `MxString` |
|
||||
| `MoveInFlag` | `MxBoolean` |
|
||||
| `MoveInJobSequenceNumber` | `MxString` |
|
||||
| `MoveInMesContainerNumber` | `MxString` |
|
||||
| `MoveInNumberWorkOrders` | `MxInteger` |
|
||||
| `MoveInOperatorName` | `MxString` |
|
||||
| `MoveInPartNumbers` | `MxString` |
|
||||
| `MoveInReadyFlag` | `MxBoolean` |
|
||||
| `MoveInSuccessFlag` | `MxBoolean` |
|
||||
| `MoveInWorkOrderNumbers` | `MxString` |
|
||||
| `MoveOutBatchID` | `MxInteger` |
|
||||
| `MoveOutFlag` | `MxBoolean` |
|
||||
| `MoveOutCompleteFlag` | `MxBoolean` |
|
||||
| `MoveOutErrorText` | `MxString` |
|
||||
| `MoveOutMesContainerNum` | `MxString` |
|
||||
| `MoveOutNumberWorkOrders` | `MxInteger` |
|
||||
| `MoveOutOperatorName` | `MxString` |
|
||||
| `MoveOutPartNumbers` | `MxString` |
|
||||
| `MoveOutWorkOrderNumbers` | `MxString` |
|
||||
| `MoveOutReadyFlag` | `MxBoolean` |
|
||||
| `MoveOutSuccessfulFlag` | `MxBoolean` |
|
||||
|
||||
All listed MES receiver user attributes were `MxCategoryWriteable_USC_Lockable`, `MxSecurityOperate`, and `MxUnLocked` in the snapshot.
|
||||
|
||||
## Instance Topology
|
||||
|
||||
All parent instances observed:
|
||||
|
||||
```text
|
||||
TestMachine_001
|
||||
TestMachine_002
|
||||
TestMachine_003
|
||||
TestMachine_004
|
||||
TestMachine_005
|
||||
TestMachine_006
|
||||
TestMachine_007
|
||||
TestMachine_008
|
||||
TestMachine_009
|
||||
TestMachine_010
|
||||
TestMachine_011
|
||||
TestMachine_012
|
||||
TestMachine_013
|
||||
TestMachine_014
|
||||
TestMachine_015
|
||||
TestMachine_016
|
||||
TestMachine_017
|
||||
TestMachine_018
|
||||
TestMachine_019
|
||||
TestMachine_020
|
||||
```
|
||||
|
||||
For each parent, the galaxy contains:
|
||||
|
||||
- `DelmiaReceiver_NNN` with hierarchical name `TestMachine_NNN.DelmiaReceiver`.
|
||||
- `MESReceiver_NNN` with hierarchical name `TestMachine_NNN.MESReceiver`.
|
||||
|
||||
Representative instance snapshots:
|
||||
|
||||
| Instance | Hierarchical name | Attributes | Scripts | Checkout |
|
||||
| --- | --- | ---: | ---: | --- |
|
||||
| `TestMachine_001` | `TestMachine_001` | 282 | 22 | `notCheckedOut` |
|
||||
| `DelmiaReceiver_001` | `TestMachine_001.DelmiaReceiver` | 179 | 36 | `notCheckedOut` |
|
||||
| `MESReceiver_001` | `TestMachine_001.MESReceiver` | 110 | 25 | `notCheckedOut` |
|
||||
|
||||
The parent instance shape matches `$TestMachine` by count and script metadata. `DelmiaReceiver_001` has one more attribute than `$TestMachine.DelmiaReceiver` in the captured snapshot; the extra field should be treated as instance/runtime metadata until a version-specific diff tool reports the exact delta.
|
||||
|
||||
## Operational Notes For LLM Automation
|
||||
|
||||
- Prefer `object snapshot --llm-json` for template and instance discovery.
|
||||
- Use `instance list --pattern '%TestMachine%' --llm-json` for current topology before editing.
|
||||
- Treat `$TestMachine` as an extension of `$gMachine`; verify with `object lineage` first, then snapshot relationship fields, then package fallback/unavailable details.
|
||||
- Use `template instantiate --create-contained` when creating `TestMachine_*` instances so `DelmiaReceiver` and `MESReceiver` child objects are created with the parent.
|
||||
- Edit embedded child objects by targeting the child instance tagname, such as `DelmiaReceiver_001`, or its hierarchical name when a command supports hierarchical lookup.
|
||||
- Do not mutate `$TestMachine` until the existing checkout state is understood; the template was `checkedOutToMe` during capture.
|
||||
- Direct scalar value readback for many template attributes is not exposed by the current generic attribute value path.
|
||||
- Direct script body readback is not exposed by the current generic value path; use `object scripts get --llm-json` package fallback for reads and `object scripts set` for script body attribute writes.
|
||||
- Extended attributes failed because the local COM type library was not registered.
|
||||
Reference in New Issue
Block a user