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