og-workspaces

OpenGate Workspaces skill

Workspaces are the OpenGate UI top-level containers (Web API /api/v1); each workspace owns N dashboards; each dashboard is a grid of widgets. The og CLI turns them into an editable local directory tree (pull) and back (wrap/deploy), extracting embedded JavaScript into real .js files.

Prerequisite: og login WITHOUT --no-web (workspace/dashboard commands use the Web API token). Quirk: OpenGate allows one active web session per user — a browser login steals the CLI session; og re-signs-in automatically on 401.

Local directory structure (what pull produces / wrap expects)

wsroot/
└── <workspace-slug>/                          # e.g. dashboards-adif
    ├── workspace.json                         # metadata only — dashboards array is STRIPPED
    └── NN__<dashboard-slug>/                  # NN__ prefix preserves array order, e.g. 00__visualizaci-n-pbi
        ├── dashboard.json                     # dashboard metadata + _workspaceLayout block
        └── NN__<widget-type>__<wid>/          # e.g. 00__customchart__1727269767709-0
            ├── widget.json                    # GridItem: layout (x,y,w,h,i) + definition
            └── _widgetConfigCode.js           # extracted JS (when present)

Rules:

• workspace.json MUST NOT embed the dashboards array — the CLI derives it from subdirectories.
• dashboard.json MUST include _workspaceLayout (x,y,w,h,id) linking it to the workspace grid.
• widget.json MUST be a full GridItem (layout coords AND definition), not a bare widget config.
• JS extraction is DECLARED, not guessed. Widget code fields, matched at any depth: _widgetConfigCode, _formatterCode, formatter, script, code, fn, expression. A declared field becomes a sibling .js file whenever present — even when empty — so its filename never moves because you edited the code. Nested fields keep their keypath in the filename (columns__0__formatter.js, columns__2___formatterCode.js). Edit the .js files, NOT the JSON copies.
• operation is NOT a code field: it carries an operation name (REFRESH_INFO).
• Transitional fallback (widgets only): an UNDECLARED field whose content looks like JavaScript (long, with function/return/=>/const/let/var) is still extracted, but pull prints a hint: on stderr naming it. Report those so the field gets declared — the heuristic misses code written as a bare assignment, and fires on prose.
• A .js file the family does not declare (your own helper.js, generated typings) is IGNORED by wrap — reported with a hint:, never uploaded as a payload field.
• The cycle is content-lossless in the sense that wrap reproduces an equivalent widget config: the decoded JSON trees compare equal. It is NOT a byte-for-byte or SHA256 match — key order and null/default serialisation differ. Two real round-trip defects (an object keyed by number turning into an array; a key containing __ colliding with the separator) were fixed in v2.1.0.