wwtools/graccesscli/docs/template-instance-editing.md

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:

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:

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:

graccess object snapshot --galaxy ZB --name TestMachine_001 --type instance --llm-json

Prefer intent wrappers for IDE concepts:

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:

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

If the template starts with $, quote it in 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:

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:

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:

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:

graccess area create --galaxy ZB --template '$Area' --name Area_Test --confirm --confirm-target '$Area' --llm-json

Equivalent lower-level form:

graccess template instantiate --galaxy ZB --name '$Area' --type template --new-name Area_Test --create-contained --confirm --confirm-target '$Area'

Verify the area:

graccess object get --galaxy ZB --name Area_Test --type instance --json

Edit an area like any other instance:

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:

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:

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:

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

Create an engine instance only after confirming the correct platform/engine template for the target galaxy:

graccess engine create --galaxy ZB --template '$AppEngine' --name AppEngine_Test --confirm --confirm-target '$AppEngine' --llm-json

Equivalent lower-level form:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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

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:

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:

graccess instance deploy --galaxy ZB --name TestMachine_001 --type instance --confirm --confirm-target TestMachine_001

Undeploy:

graccess instance undeploy --galaxy ZB --name TestMachine_001 --type instance --confirm --confirm-target TestMachine_001

Upload runtime changes:

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:

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:

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

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:

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.

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.

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

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