wwtools/graccesscli/docs/zb-testmachine.md

# 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. Package-only script body/expression fields are not persisted by GRAccess `IAttribute.SetValue`; use the IDE/package path for those edits.
- Extended attributes failed because the local COM type library was not registered.