wwtools/graccesscli/docs/script-editing.md

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:

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:

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 settings set --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --trigger-period-ms 500 --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	object scripts get package fallback for script body attributes such as ExecuteText
Object script mutable settings	object scripts settings set --trigger-type, --trigger-period-ms
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:

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

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

graccess script-library import --galaxy ZB --path '.\scripts\CommonScripts.aaslib' --confirm --confirm-target '.\scripts\CommonScripts.aaslib'

The galaxy-level import command is also available:

graccess galaxy import-script-library --galaxy ZB --path '.\scripts\CommonScripts.aaslib' --confirm --confirm-target '.\scripts\CommonScripts.aaslib'

After import, list libraries again:

graccess script-library list --galaxy ZB --json

Edit Script-Like Attributes

Some templates store expressions, declarations, triggers, or script fragments in attributes. Find candidates:

$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 writable attribute, edit it through the normal template edit flow. Script extension attributes are looked up through ConfigurableAttributes first, then Attributes.

For local ScriptExtension objects, body fields such as ExecuteText, StartupText, OnScanText, and Expression are package-only. GRAccess IAttribute.SetValue can return success without persisting package-only fields, so object scripts set and object scripts settings set --expression fail fast when the attribute category starts with MxCategoryPackageOnly. Use the IDE or a future package-rewrite path for those fields.

graccess object checkout --galaxy ZB --name TestMachine --type template --confirm --confirm-target TestMachine
graccess object attribute value set --galaxy ZB --name TestMachine --type template --attribute SomeWritableScriptSetting --value Updated --data-type string --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 writable script setting' --confirm --confirm-target TestMachine

Update periodic script settings and lock the interval for deployment inheritance:

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:

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:

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:

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:

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 wrapper below creates the same ScriptExtension primitive and can initialize mutable settings:

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 --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, body text still needs the IDE/package path when the projected body attributes are package-only.

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:

$pkg = '.\template-work\TestMachine.aaPKG'
graccess objects export --galaxy ZB --type template --name TestMachine --output $pkg --confirm --confirm-target $pkg

Import:

graccess galaxy import-objects --galaxy ZB --file '.\template-work\TestMachine.aaPKG' --overwrite --confirm --confirm-target '.\template-work\TestMachine.aaPKG'

For conflict-aware import:

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:

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:

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

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 settings set --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --trigger-period-ms 500 --confirm --confirm-target TestMachine --llm-json

The local GRAccess examples sometimes show Template.Scripts[index].ScriptString, but this repository's installed ArchestrA.GRAccess.dll does not expose a public object script collection. It exposes script extension projections as attributes and package records. The CLI can read body text through exported package parsing and can write mutable settings through IAttribute.SetValue; package-only body/expression fields are not persisted by that GRAccess setter.