Joseph Doherty
131 lines
6.0 KiB
Markdown
131 lines
6.0 KiB
Markdown
# Parsing Scripts And Script Libraries
|
|
|
|
This guide describes how to capture scripts related to a template such as `TestMachine`.
|
|
|
|
GRAccess exposes script libraries directly through `IScriptLibraries` and `IScriptLibrary`. Object-level scripts are less direct: depending on object type and System Platform version, they may appear as attributes, extension attributes, or only inside exported object packages.
|
|
|
|
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 workflows, include object script metadata in the snapshot first:
|
|
|
|
```powershell
|
|
graccess object snapshot --galaxy ZB --name TestMachine --type template --llm-json
|
|
graccess object scripts list --galaxy ZB --name TestMachine --type template --llm-json
|
|
graccess object scripts get --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt.ExecuteText --llm-json
|
|
graccess object scripts get --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --llm-json
|
|
```
|
|
|
|
Direct object script body readback is version-specific. The CLI tries direct GRAccess metadata first, then exports the target object to a temporary `.aaPKG`, recurses through nested package archives, and parses binary UTF-16 package records for `ScriptExtension` content. For script extension names, a bare script such as `UpdateTestChangingInt` resolves to `UpdateTestChangingInt.ExecuteText`. Explicit fields such as `UpdateTestChangingInt.StartupText` are preserved.
|
|
|
|
The exported package fallback can read script text fields such as `ExecuteText`, `DeclarationsText`, `StartupText`, `ShutdownText`, `OnScanText`, `OffScanText`, and `Expression` when present. When body access is unavailable from both direct GRAccess and package data, `object scripts get` reports that in structured output.
|
|
|
|
## Script Library Inventory
|
|
|
|
List script libraries:
|
|
|
|
```powershell
|
|
graccess script-library list --galaxy ZB --json
|
|
```
|
|
|
|
The current CLI returns library names. The underlying GRAccess API for `IScriptLibrary` exposes `Name` and `Export(path)`.
|
|
|
|
## Export Script Libraries
|
|
|
|
Export is the authoritative way to preserve script library content:
|
|
|
|
```powershell
|
|
$out = '.\template-snapshots\script-libraries'
|
|
New-Item -ItemType Directory -Force -Path $out | Out-Null
|
|
|
|
graccess script-library export --galaxy ZB --name CommonScripts --output "$out\CommonScripts.aaslib" --confirm --confirm-target "$out\CommonScripts.aaslib"
|
|
```
|
|
|
|
`script-library export` writes a local file, so the CLI requires confirmation and a matching `--confirm-target` equal to the output path.
|
|
|
|
To export every listed script library, parse the JSON list and call export for each name:
|
|
|
|
```powershell
|
|
$galaxy = 'ZB'
|
|
$out = '.\template-snapshots\script-libraries'
|
|
New-Item -ItemType Directory -Force -Path $out | Out-Null
|
|
|
|
$libs = graccess script-library list --galaxy $galaxy --json | ConvertFrom-Json
|
|
foreach ($lib in $libs) {
|
|
$name = $lib.Name
|
|
$path = Join-Path $out "$name.aaslib"
|
|
graccess script-library export --galaxy $galaxy --name $name --output $path --confirm --confirm-target $path
|
|
}
|
|
```
|
|
|
|
## Object-Level Script Discovery
|
|
|
|
For a template such as `TestMachine`, first inspect attributes and extended attributes for script-like names:
|
|
|
|
```powershell
|
|
graccess object attributes --galaxy ZB --name TestMachine --type template --json
|
|
graccess object extended-attributes --galaxy ZB --name TestMachine --type template --json
|
|
```
|
|
|
|
PowerShell classification:
|
|
|
|
```powershell
|
|
$attrs = Get-Content '.\template-snapshots\TestMachine.attributes.json' -Raw | ConvertFrom-Json
|
|
$extended = Get-Content '.\template-snapshots\TestMachine.extended-attributes.json' -Raw | ConvertFrom-Json
|
|
$all = (@($attrs) + @($extended)) | Sort-Object Name -Unique
|
|
|
|
$scripts = $all | Where-Object {
|
|
$_.Name -match '(?i)script|execute|trigger|expression|declaration|startup|shutdown|scan'
|
|
}
|
|
|
|
$scripts | Sort-Object Name | Select-Object Name, DataType, Category, Locked
|
|
```
|
|
|
|
This discovers script-related setting names and metadata. For bodies, prefer `object scripts get --llm-json` or `object snapshot --llm-json`; both can include package-backed script text when GRAccess export is available. Normal CLI script parsing must not query the Galaxy SQL database; SQL is development verification/debug-only.
|
|
|
|
## Export Template Objects For Script Bodies
|
|
|
|
Use object export when you need the full object configuration, including script bodies, declarations, triggers, and extension payloads that are not exposed as simple attribute metadata:
|
|
|
|
```powershell
|
|
$out = '.\template-snapshots\TestMachine'
|
|
New-Item -ItemType Directory -Force -Path $out | Out-Null
|
|
$pkg = Join-Path $out 'TestMachine.aaPKG'
|
|
|
|
graccess objects export --galaxy ZB --type template --name TestMachine --output $pkg --confirm --confirm-target $pkg
|
|
```
|
|
|
|
The exported package should be treated as the complete vendor-owned representation. Use it as the source of truth when CLI JSON and GRAccess attribute metadata do not expose script content.
|
|
|
|
For a galaxy-wide reference export:
|
|
|
|
```powershell
|
|
$pkg = '.\template-snapshots\ZB.export.aaPKG'
|
|
graccess galaxy export-all --galaxy ZB --output $pkg --json
|
|
```
|
|
|
|
`galaxy export-all` is read-only from the galaxy perspective but writes an output file.
|
|
|
|
## Suggested Parse Bundle
|
|
|
|
A practical template parse bundle should include:
|
|
|
|
| File | Command |
|
|
|---|---|
|
|
| `object.json` | `object get` |
|
|
| `attributes.json` | `object attributes` |
|
|
| `configurable-attributes.json` | `object attributes --configurable` |
|
|
| `extended-attributes.json` | `object extended-attributes` |
|
|
| `attribute-groups.json` | Local classifier from `attribute-parsing.md` |
|
|
| `template.aaPKG` | `objects export` |
|
|
| `script-libraries/*.aaslib` | `script-library export` |
|
|
|
|
## Notes On GRAccess Script Collections
|
|
|
|
Some GRAccess examples refer to `Template.Scripts[index].ScriptString`. The local installed GRAccess interop and docs used by this CLI expose `ScriptExtension` content through script-like attributes and exported package records instead. Use `object scripts list/get` as the supported discovery and readback contract for this repository.
|