wwtools/graccesscli/docs/template-parsing.md

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:

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:

graccess session start --galaxy ZB --node .

After a session is active, logged-in commands can omit --node:

graccess template list --galaxy ZB --pattern '%TestMachine%' --json

Without a session, include --node . on each command:

graccess template list --galaxy ZB --node . --pattern '%TestMachine%' --json

For LLM-driven parsing, prefer the bundled machine snapshot before running narrower commands:

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.

graccess template list --galaxy ZB --pattern '%TestMachine%' --json

If the template name starts with $, quote it with single quotes in PowerShell:

graccess template list --galaxy ZB --pattern '%$TestMachine%' --json

Read Template Identity

Use object get with --type template to fetch the core object record:

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:

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:

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:

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:

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:

graccess object attributes --galaxy ZB --name TestMachine --type template --json

Use --configurable when you only need configurable attributes:

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:

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:

graccess object extended-attributes --galaxy ZB --name TestMachine --type template --json

You can scope the request with an attribute name and hierarchy level:

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:

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:

$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:

graccess object query-condition --galaxy ZB --type all --condition derivedOrInstantiatedFrom --value TestMachine --json

All descendants based on the same base template:

graccess object query-condition --galaxy ZB --type all --condition basedOn --value TestMachine --json

Objects contained by the template:

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:

$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:

$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.