wwtools/graccesscli/docs/attribute-editing.md

Editing Template Attributes

This guide describes how to edit template attributes for an existing GRAccess template such as TestMachine.

Read attribute-parsing.md first so you know the exact attribute names and current settings before changing anything.

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 edits, use --llm-json and validate first:

graccess object snapshot --galaxy ZB --name TestMachine --type template --llm-json
graccess object attribute value set --galaxy ZB --name TestMachine --type template --attribute Description --value Updated --data-type string --confirm --confirm-target TestMachine --dry-run --llm-json

Edit Flow

Wrap attribute edits in the standard GRAccess object edit flow:

graccess object checkout --galaxy ZB --name TestMachine --type template --confirm --confirm-target TestMachine

# Attribute mutation commands.

graccess object save --galaxy ZB --name TestMachine --type template --confirm --confirm-target TestMachine
graccess object checkin --galaxy ZB --name TestMachine --type template --comment 'Edit template attributes' --confirm --confirm-target TestMachine

If any mutation fails, do not continue with more changes until the failure is understood. Use object undo-checkout when the edit should be discarded.

Confirm The Target Attribute

Before editing a specific attribute:

graccess object attribute get --galaxy ZB --name TestMachine --type template --attribute Description --json

For setting-family edits, find candidate names first:

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

Set Attribute Values

Use object attribute set:

graccess object attribute set --galaxy ZB --name TestMachine --type template --attribute Description --value 'Updated description' --data-type string --confirm --confirm-target TestMachine

Supported --data-type values:

Data type	Conversion
string	MxValue.PutString(...)
bool, boolean, mxboolean	MxValue.PutBoolean(...)
int, integer, mxinteger	MxValue.PutInteger(...)
float, mxfloat	MxValue.PutFloat(...)
double, mxdouble	MxValue.PutDouble(...)

Examples:

graccess object attribute set --galaxy ZB --name TestMachine --type template --attribute EnableFeature --value true --data-type bool --confirm --confirm-target TestMachine

graccess object attribute set --galaxy ZB --name TestMachine --type template --attribute ScanPeriod --value 1000 --data-type int --confirm --confirm-target TestMachine

graccess object attribute set --galaxy ZB --name TestMachine --type template --attribute Gain --value 1.25 --data-type double --confirm --confirm-target TestMachine

The current CLI does not support array values, time values, references, or complex MxValue payloads. Use export/import or extend CreateMxValue(...) when those are needed.

Lock Or Unlock Attributes

Use object attribute lock:

graccess object attribute lock --galaxy ZB --name TestMachine --type template --attribute Description --locked MxPropertyUnlocked --confirm --confirm-target TestMachine

The --locked value must match a local MxPropertyLockedEnum member. The enum parser is case-insensitive and also accepts values with or without a galaxy_ prefix when such a prefix exists.

Change Attribute Security

Use object attribute security:

graccess object attribute security --galaxy ZB --name TestMachine --type template --attribute Description --security MxSecurityOperate --confirm --confirm-target TestMachine

The --security value must match a local MxSecurityClassification member.

Change Attribute Buffer Flag

Use object attribute buffer:

graccess object attribute buffer --galaxy ZB --name TestMachine --type template --attribute Description --has-buffer --confirm --confirm-target TestMachine

To clear the flag, omit --has-buffer:

graccess object attribute buffer --galaxy ZB --name TestMachine --type template --attribute Description --confirm --confirm-target TestMachine

Add A UDA

Use object uda add:

graccess object uda add --galaxy ZB --name TestMachine --type template --uda CustomCode --data-type MxString --category MxCategoryWriteable_USC --security MxSecurityUndefined --confirm --confirm-target TestMachine

Array UDA:

graccess object uda add --galaxy ZB --name TestMachine --type template --uda CustomArray --data-type MxString --category MxCategoryWriteable_USC --security MxSecurityUndefined --is-array --array-count 10 --confirm --confirm-target TestMachine

Rename, Update, Or Delete A UDA

Rename:

graccess object uda rename --galaxy ZB --name TestMachine --type template --uda CustomCode --new-name CustomCode2 --confirm --confirm-target TestMachine

Update metadata:

graccess object uda update --galaxy ZB --name TestMachine --type template --uda CustomCode2 --data-type MxString --category MxCategoryWriteable_USC --security MxSecurityUndefined --confirm --confirm-target TestMachine

Delete:

graccess object uda delete --galaxy ZB --name TestMachine --type template --uda CustomCode2 --confirm --confirm-target TestMachine

Edit Extensions

Use extension commands only when you know the supported extension type and primitive name for the template.

graccess object extension add --galaxy ZB --name TestMachine --type template --extension-type ScriptExtension --primitive OnScan --object-extension --confirm --confirm-target TestMachine

graccess object extension rename --galaxy ZB --name TestMachine --type template --extension-type ScriptExtension --primitive OnScan --new-name OnScan2 --object-extension --confirm --confirm-target TestMachine

graccess object extension delete --galaxy ZB --name TestMachine --type template --extension-type ScriptExtension --primitive OnScan2 --object-extension --confirm --confirm-target TestMachine

Edit History Settings

History settings are usually stored as attributes or extension attributes. First identify candidate names:

$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
$history = (@($attrs) + @($extended)) | Where-Object {
  $_.Name -match '(?i)hist|history|historian|storage|trend'
} | Sort-Object Name -Unique

$history | Select-Object Name, DataType, Category, Locked

Then edit a known setting with object attribute set, lock, security, or buffer commands. Example:

graccess object attribute set --galaxy ZB --name TestMachine --type template --attribute HistoryEnabled --value true --data-type bool --confirm --confirm-target TestMachine

If the setting value is not a simple string/bool/int/float/double, use export/import or extend CLI value serialization first.

Edit I/O Settings

I/O settings may be attributes, object-reference assignments, or extension payloads.

Find likely attributes:

$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 attribute-backed settings:

graccess object attribute set --galaxy ZB --name TestMachine --type template --attribute ScanPeriod --value 1000 --data-type int --confirm --confirm-target TestMachine

Edit object-level assignment properties with object set when applicable:

graccess object set --galaxy ZB --name TestMachine --type template --property host --value AppEngine_001 --confirm --confirm-target TestMachine

If the COM setter requires an object reference instead of a string, extend the CLI to resolve the named object and assign that object.

Edit Alarm Settings

Alarm settings are commonly attribute-backed.

Find likely alarm attributes:

$alarm = (@($attrs) + @($extended)) | Where-Object {
  $_.Name -match '(?i)alarm|alert|limit|priority|severity|deadband|deviation|rate|roc|hihi|lolo|(^|[._])hi($|[._])|(^|[._])lo($|[._])|ack'
} | Sort-Object Name -Unique

$alarm | Select-Object Name, DataType, Category, SecurityClassification, Locked

Edit simple value-backed settings:

graccess object attribute set --galaxy ZB --name TestMachine --type template --attribute AlarmPriority --value 500 --data-type int --confirm --confirm-target TestMachine

Security and lock changes use the same attribute commands:

graccess object attribute security --galaxy ZB --name TestMachine --type template --attribute AlarmPriority --security MxSecurityOperate --confirm --confirm-target TestMachine
graccess object attribute lock --galaxy ZB --name TestMachine --type template --attribute AlarmPriority --locked MxPropertyLocked --confirm --confirm-target TestMachine

Verify Attribute Edits

After checkin, re-read the edited metadata:

graccess object attribute get --galaxy ZB --name TestMachine --type template --attribute Description --json
graccess object attributes --galaxy ZB --name TestMachine --type template --configurable --json

The current CLI does not read back attribute values, so value verification requires one of:

Need	Path
Confirm metadata changed	object attribute get or object attributes
Confirm simple value changed	Add value readback support
Confirm full vendor configuration	Export object and compare package content with vendor tooling

Recommended CLI Extension For Full Attribute Editing

To fully support history, I/O, alarm, and script-related settings as first-class CLI operations, add:

graccess object attribute value get --galaxy ZB --name TestMachine --type template --attribute AttrName --json
graccess object attribute value set --galaxy ZB --name TestMachine --type template --attribute AttrName --value-json file.json --confirm --confirm-target TestMachine

The implementation should serialize IAttribute.Value defensively and support complex MxValue shapes beyond the current scalar string, bool, int, float, and double conversions.