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

```powershell
graccess session start --galaxy ZB --node .
```

Without a session, add `--node .` to each command.

For LLM-driven edits, use `--llm-json` and validate first:

```powershell
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:

```powershell
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:

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

For setting-family edits, find candidate names first:

```powershell
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`:

```powershell
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:

```powershell
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`:

```powershell
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`:

```powershell
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`:

```powershell
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`:

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

## Add A UDA

Use `object uda add`:

```powershell
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:

```powershell
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:

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

Update metadata:

```powershell
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:

```powershell
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.

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

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

```powershell
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:

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

```powershell
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:

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

```powershell
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:

```powershell
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:

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

```powershell
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:

```powershell
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:

```powershell
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:

```text
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.