Hub Editor

Hub Editor

Modify a Datex Studio hub configuration to add toolbar buttons, wire click flows, and integrate reports or other actions into a hub UI.

See also: hub-creator — authoring a NEW hub from scratch (this skill is for modifying existing hubs).

References

• ../datex-studio-shared/branch-setup.md — Branch selection (shared across skills)
• ../datex-studio-shared/configuration-roundtrip.md — canonical dxs configuration get → extract .json → edit → upsert round-trip and the silent-wipe bug it avoids
• ../datex-studio-shared/flow-code-patterns.md — $utils.isDefined(), date defaulting, $shell.Reports.open{ref}()
• references/hub-config-api.md — hub-specific notes on top of the canonical round-trip (and dxs api --raw / -D / -O fallback)
• references/toolbar-and-click-flows.md — toolbar[] and flows[] JSON structure, clickFlowConfig reference, common patterns

Dependencies

• requirements-gathering skill — invoked to produce a requirements brief if one doesn't already exist
• function-creator skill — invoked when the click flow does not yet exist as a Datex Studio function

CLI Status

Hub edits go through dxs configuration — the generic CRUD primitive over every platform configuration type (hub, grid, form, flow, footprintquerymanager, appconfig, etc.; run dxs configuration types to list all). The round-trip is the canonical pattern in ../datex-studio-shared/configuration-roundtrip.md. get -O writes the full server envelope; you MUST extract the inner .json body before upsert, or the push silently wipes the config (this bug was first caught on a hub):

dxs configuration get hub <configId> -b <branchId> -O envelope.json   # fetch (full envelope)
jq .json envelope.json > body.json                                    # extract inner body — REQUIRED
# edit body.json locally (toolbar[], flows[], …)
dxs configuration upsert hub -b <branchId> -D body.json               # push inner body

The branch is the source of truth; envelope.json / body.json are throwaway scratch files. There is no dxs hub subcommand and no field-level patching — you fetch the whole document, edit JSON, and push the whole document back. See ../datex-studio-shared/configuration-roundtrip.md for the canonical round-trip and references/hub-config-api.md for hub-specific details.

Note on naming: dxs configuration operates on platform configurations (hubs, grids, etc.) on a branch. dxs config (also aliased as dxs settings) operates on local CLI settings stored in ~/.datex/config.yaml. Prefer dxs settings in any context that also discusses dxs configuration — it eliminates the easy confusion.

Workflow

[Phase 1: Setup]
Follow branch-setup.md for branch selection
        |
[requirements brief in context?]
  +-----+-----+
  |            |
 YES          NO → invoke requirements-gathering
  |            |
  +-----+------+
        |
[Phase 2: Locate the hub]
Identify hub by reference name (e.g., inventory_hub)
        |
dxs source explore config <hub_ref> --branch <id>
  → extract: hub config ID
        |
[Phase 3: Fetch current hub configuration]
dxs configuration get hub <configId> -b <branchId> -O envelope.json
jq .json envelope.json > body.json          ← extract inner body (REQUIRED)
cp body.json body.json.orig                 ← save for diff
        |
[Phase 4: Plan the change]
What's changing?
  +------+------+------+
  |      |      |      |
 ADD   MODIFY REMOVE  RENAME
  toolbar       button       click flow
        |
[Phase 5: Click-flow prerequisite (if adding/changing a button)]
Does the target click flow function exist?
  +-----+-----+
  |           |
 YES         NO
  |           |
 use it    invoke function-creator
  |        (writes the .ts code,
  |         upserts the function,
  |         returns reference name)
  +-----+-----+
        |
[Phase 6: Edit body.json]
Modify toolbar[] and flows[] arrays per references/toolbar-and-click-flows.md
        |
[Phase 7: Validate locally]
python -m json.tool body.json > /dev/null   ← syntactic check
diff -u body.json.orig body.json            ← review the change
        |
[Phase 8: Push updated config]
dxs configuration upsert hub -b <branchId> -D body.json
        |
[Phase 9: Verify]
Reload the hub in the running app (or re-fetch and diff)
to confirm the change took effect

Phase Details

Phase 1: Setup

Follow ../datex-studio-shared/branch-setup.md. The branch ID is required by every dxs configuration command (-b/--branch) — pass it explicitly in skill examples; don't rely on implicit scoping.

Phase 2: Locate the hub

You need the hub configuration ID (configId). The simplest path:

dxs source explore config <hub_reference_name> --branch <branch_id>

This returns the hub config metadata, including its id. If you don't know the reference name, list configs filtered to the hub type:

dxs source explore configs --branch <branch_id> | grep -i hub

Hub configs use a configurationTypeId distinct from datasources (6) and functions (9). Check the dxs source explore configs output to see the type IDs in use on your branch.

Phase 3: Fetch current hub configuration

dxs configuration get hub <configId> -b <branch_id> -O envelope.json
jq .json envelope.json > body.json    # extract the inner body — see configuration-roundtrip.md
cp body.json body.json.orig           # diff target for Phase 7

get -O writes the full server envelope; upsert -D expects only the inner .json body. Skipping the extraction step pushes the envelope back and silently wipes the config — see ../datex-studio-shared/configuration-roundtrip.md. Always start from a fresh fetch — never edit a stale copy. See references/hub-config-api.md for hub-specific details.

Phase 4: Plan the change

The hub configuration has two interconnected arrays:

A typical "add a toolbar button that launches a report" change touches both arrays: a new entry in toolbar[] and the click flow reference added to flows[]. See references/toolbar-and-click-flows.md for the JSON structure and the common patterns.

Phase 5: Click-flow prerequisite

Hub toolbar buttons execute a Datex Studio function as their click handler. If the target click flow function doesn't exist yet, invoke function-creator first. The click flow code typically:

1. Reads the hub's date-range / context inputs from $flow.inParams
2. Applies defaults for any missing values — see ../datex-studio-shared/flow-code-patterns.md for the canonical date-defaulting pattern using $utils.isDefined()
3. Calls $shell.Reports.open{ref}() (or another shell action) with the resolved parameters

Reference ../datex-studio-shared/flow-code-patterns.md when authoring the click flow so the function-creator's output uses $utils.isDefined() (not != null) and the documented date-defaulting block.

Phase 6: Edit body.json

Use a JSON editor or jq to add/modify entries. Two safety rules:

• Preserve everything you didn't change. Hub configs contain UI state, version stamps, and properties unrelated to your edit. dxs configuration upsert replaces the entire object; missing fields are deleted.
• Keep toolbar[] and flows[] consistent. Every clickFlowConfig.reference in toolbar[] must have a matching entry in flows[], and vice versa.

Phase 7: Validate locally

python -m json.tool body.json > /dev/null      # JSON-parses?
diff -u body.json.orig body.json                # review actual changes

body.json.orig was saved in Phase 3 right after extraction — the diff is your only structural review before pushing.

Phase 8: Push updated config

dxs configuration upsert hub -b <branch_id> -D body.json

Push the extracted inner body (body.json), never the raw envelope.json. The -D/--data-file flag reads the body from a file, bypassing shell escaping entirely — so \r\n sequences and embedded quotes in the JSON are no longer a concern.

Phase 9: Verify

Re-fetch the config and compare inner bodies:

dxs configuration get hub <configId> -b <branch_id> -O envelope-after.json
jq .json envelope-after.json > body-after.json
diff -u body.json body-after.json

The diff should be empty (or contain only server-side fields like updatedDateTime). Reload the hub in the running app to confirm the new toolbar button appears and the click flow fires correctly.

Common Operations

Key Rules

• Extract the inner .json body before upsert. get -O writes the full envelope; jq .json envelope.json > body.json. Pushing the raw envelope silently wipes the config — see ../datex-studio-shared/configuration-roundtrip.md.
• Never edit a stale body.json. Always re-fetch with dxs configuration get hub before edits — other users or releases may have modified the hub.
• dxs configuration upsert replaces the entire config. Don't omit fields you didn't intend to change.
• toolbar[] and flows[] must stay in sync. A toolbar button without a corresponding flow entry won't fire; an orphaned flow entry is harmless but should be cleaned up.
• Click flow code must use $utils.isDefined() — see ../datex-studio-shared/flow-code-patterns.md. Native null checks misfire against Datex Studio's value model.
• $shell.Reports.open{ref}() parameter keys are case-sensitive and must match the report's ReportParameters[].Name exactly.
• Save body.json.orig after extraction. It's your only diff target before push.

Common Mistakes

After your edit, invoke post-edit-verification to surface description/JSON/schema violations. For a final review, invoke component-validator.