hub-editor

ハブエディター

Datex Studio のハブ設定を変更して、ツールバーのボタンを追加し、クリック時のフローを接続し、レポートやその他のアクションをハブ UI に統合します。

こちらもご覧ください： hub-creator — 新しいハブをゼロから作成します（このスキルは既存のハブを変更するためのものです）。

参考資料

• ../datex-studio-shared/branch-setup.md — ブランチの選択（スキル間で共有）
• ../datex-studio-shared/configuration-roundtrip.md — 標準的な dxs configuration get → .json を抽出 → 編集 → upsert のラウンドトリップと、それによって回避できるサイレントワイプのバグ
• ../datex-studio-shared/flow-code-patterns.md — $utils.isDefined()、日付のデフォルト設定、$shell.Reports.open{ref}()
• references/hub-config-api.md — 標準的なラウンドトリップに加えた、ハブ固有の注意事項（および dxs api --raw / -D / -O の代替方法）
• references/toolbar-and-click-flows.md — toolbar[] と flows[] の JSON 構造、clickFlowConfig のリファレンス、一般的なパターン

依存関係

• requirements-gathering スキル — 要件概要がまだ存在しない場合に作成するため呼び出されます
• function-creator スキル — クリック時のフローがまだ Datex Studio 関数として存在しない場合に呼び出されます

CLI の状況

ハブの編集には dxs configuration を使用します。これは、すべてのプラットフォーム設定タイプ（ハブ、グリッド、フォーム、フロー、footprintquerymanager、appconfig など）に対応する汎用 CRUD プリミティブです。すべてのタイプを一覧表示するには dxs configuration types を実行します。ラウンドトリップは ../datex-studio-shared/configuration-roundtrip.md に記載された標準的なパターンです。get -O はサーバーの完全なエンベロープを書き出します。upsert の前に、内側の .json 本文を必ず抽出してください。抽出しないと、プッシュによって設定がサイレントワイプされます（このバグはハブで初めて発見されました）。

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

ブランチが信頼できる唯一の情報源です。envelope.json / body.json は一時的な作業ファイルです。dxs hub サブコマンドも、フィールド単位のパッチ適用もありません。ドキュメント全体を取得し、JSON を編集して、ドキュメント全体をプッシュして戻します。標準的なラウンドトリップについては ../datex-studio-shared/configuration-roundtrip.md、ハブ固有の詳細については references/hub-config-api.md を参照してください。

名前に関する注意：dxs configuration は、ブランチ上のプラットフォーム設定（ハブ、グリッドなど）を操作します。dxs config（dxs settings というエイリアスもあります）は、~/.datex/config.yaml に保存されたローカル CLI 設定を操作します。dxs configuration についても扱う場面では、混同を避けやすくするため dxs settings を使用してください。

ワークフロー

[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

フェーズの詳細

フェーズ 1：セットアップ

../datex-studio-shared/branch-setup.md に従ってください。すべての dxs configuration コマンドでブランチ ID（-b/--branch）が必要です。スキルの例では明示的に指定し、暗黙のスコープ設定に依存しないでください。

フェーズ 2：ハブを特定する

ハブ設定 ID（configId）が必要です。最も簡単な方法は次のとおりです。

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

これにより、id を含むハブ設定のメタデータが返されます。参照名がわからない場合は、ハブタイプで設定を絞り込んで一覧表示します。

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

ハブ設定は、データソース（6）や関数（9）とは異なる configurationTypeId を使用します。dxs source explore configs の出力を確認し、ブランチで使用されているタイプ ID を確認してください。

フェーズ 3：現在のハブ設定を取得する

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 はサーバーの完全なエンベロープを書き出します。upsert -D が必要とするのは、内側の .json 本文だけです。抽出を省略すると、エンベロープがそのままプッシュされ、設定がサイレントワイプされます。../datex-studio-shared/configuration-roundtrip.md を参照してください。必ず最新の取得結果から始め、古いコピーを編集しないでください。ハブ固有の詳細については references/hub-config-api.md を参照してください。

フェーズ 4：変更を計画する

ハブの設定には、相互に関連する 2 つの配列があります。

配列	用途
toolbar[]	ハブのツールバーに表示される UI ボタンです。各ボタンには clickFlowConfig があります
flows[]	ハブが認識している Datex Studio フロー関数の参照です。clickFlowConfig から参照されるすべてのフローは、ここにも含まれている必要があります

「レポートを起動するツールバーボタンを追加する」場合、通常は両方の配列を変更します。toolbar[] に新しい項目を追加し、flows[] にクリックフローの参照を追加します。JSON の構造と一般的なパターンについては、references/toolbar-and-click-flows.md を参照してください。

フェーズ 5：クリックフローの前提条件

ハブのツールバーボタンは、クリック時のハンドラーとして Datex Studio 関数を実行します。対象のクリックフロー関数がまだ存在しない場合は、先に function-creator を呼び出してください。クリックフローのコードでは通常、次の処理を行います。

1. $flow.inParams からハブの日付範囲やコンテキストの入力値を読み取ります
2. 不足している値にデフォルト値を適用します。$utils.isDefined() を使う標準的な日付のデフォルト設定パターンについては、../datex-studio-shared/flow-code-patterns.md を参照してください
3. 解決済みのパラメーターを使って $shell.Reports.open{ref}()（または別のシェルアクション）を呼び出します

クリックフローを作成する際は、../datex-studio-shared/flow-code-patterns.md を参照してください。これにより、function-creator が != null ではなく $utils.isDefined() と、文書化された日付のデフォルト設定ブロックを使ったコードを生成できます。

フェーズ 6：body.json を編集する

JSON エディターまたは jq を使って、項目を追加または変更します。次の 2 つの安全ルールを守ってください。

• 変更していないものはすべて保持します。 ハブの設定には、UI の状態、バージョン情報、編集とは無関係なプロパティが含まれています。dxs configuration upsert はオブジェクト全体を置き換えるため、存在しないフィールドは削除されます。
• toolbar[] と flows[] の整合性を保ちます。 toolbar[] 内のすべての clickFlowConfig.reference に、flows[] 内の対応する項目が必要です。その逆も同様です。

フェーズ 7：ローカルで検証する

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

body.json.orig はフェーズ 3 で抽出直後に保存されています。プッシュする前に構造を確認する唯一の方法は差分です。

フェーズ 8：更新した設定をプッシュする

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

抽出した内側のボディ（body.json）をプッシュしてください。生の envelope.json は使用しないでください。-D/--data-file フラグはファイルからボディを読み込むため、シェルでのエスケープ処理を完全に回避できます。そのため、JSON 内の \r\n シーケンスや埋め込み引用符を気にする必要はありません。

フェーズ 9：検証する

設定を再取得し、内側のボディを比較します。

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

差分は空であるか、updatedDateTime などのサーバー側フィールドのみを含むはずです。実行中のアプリでハブを再読み込みし、新しいツールバーボタンが表示され、クリックフローが正しく実行されることを確認してください。

一般的な操作

操作	変更内容
レポートを開くツールバーボタンを追加する	toolbar[] に新しい項目を追加し、flows[] にクリックフローの参照を追加します。クリックフロー関数の作成が必要な場合があります
ボタンが開くレポートを変更する	クリックフロー関数のコード（$shell.Reports.open{newRef}(...)）を変更します。フロー参照が同じであれば、ハブ設定の変更は不要です
ボタンの名前やラベルを変更する	toolbar[].label（または同等の表示フィールド）を変更します。フローの変更は不要です
ボタンを削除する	toolbar[] から項目を削除し、flows[] から（参照先がなくなった）参照も削除します
ボタンの順序を変更する	toolbar[] の項目を並べ替えます

重要なルール

• アップサートの前に、内側の.json本文を取り出してください。 get -O はエンベロープ全体を書き出します。jq .json envelope.json > body.json を実行してください。未加工のエンベロープをプッシュすると、設定が気付かないうちに消去されます。../datex-studio-shared/configuration-roundtrip.mdを参照してください。
• 古いbody.jsonは絶対に編集しないでください。 編集前に必ずdxs configuration get hubで再取得してください。他のユーザーやリリースによってハブが変更されている場合があります。
• dxs configuration upsertは設定全体を置き換えます。 変更するつもりのないフィールドも省略しないでください。
• toolbar[]とflows[]は常に同期させてください。 対応するフロー項目のないツールバーボタンは実行されません。孤立したフロー項目は害はありませんが、削除してください。
• クリックフローのコードでは$utils.isDefined()を使用してください。../datex-studio-shared/flow-code-patterns.mdを参照してください。通常のnullチェックでは、Datex Studioの値モデルに対して誤作動します。
• $shell.Reports.open{ref}()のパラメーターキーは大文字と小文字を区別し、レポートのReportParameters[].Nameと完全に一致させる必要があります。
• 抽出後にbody.json.origを保存してください。 プッシュ前の差分比較に使える唯一の対象です。

よくある間違い

間違い	修正方法
get -Oの出力である未加工のenvelope.jsonを、そのままupsert -Dにプッシュする	ハブを気付かないうちに消去します（toolbar/flows/onInitFlowConfigがnullにリセットされます）。先に抽出します：jq .json envelope.json > body.jsonを実行し、その後upsert -D body.jsonを実行してください。configuration-roundtrip.mdを参照してください
dxs hub get / dxs hub updateを試す	これらのコマンドは存在しません。dxs configuration get hub / dxs configuration upsert hubを使用してください
ハブの取得にdxs config get <id>を使う	dxs config（エイリアスはdxs settings）はローカルのCLI設定を操作するもので、プラットフォーム設定は操作しません。dxs configuration get hub <id> -b <branchId>を使用してください
手作業でURLを組み立てるためにendpoints.pyを読む	dxs configurationはKNOWN_TYPES内のすべてのタイプに対応しているため、URLパターンを調べる必要はもうありません。dxs configurationが対応していないエンドポイントにはdxs apiを使用してください
dxs api --saveを試す	そのフラグは一度も存在したことがありません。dxs apiで-O/--output-file（未加工のJSONを書き出します）を使うか、dxs configuration get ... -Oを使用してください
大きな本文のためにPythonのhttpx.put()ヘルパーに頼る	もう必要ありません。dxs configuration upsert -D <file>とdxs api PUT -D <file>はどちらもファイルから本文を読み込み、シェルのエスケープ処理を回避します
プリアンブルを取り除くために`dxs api GET ...	tail -n +2`にパイプする
dxs configurationコマンドで-b/--branchを忘れる	このフラグは必須です。すべての例で明示的に指定してください
flows[]に追加せず、toolbar[]のボタンを追加する	ボタンは表示されますが、実行されません。両方の配列で同じクリックフローを参照する必要があります
クリックフローのコードで!= nullや!startDateを使う	$utils.isDefined(startDate)を使用してください。Datex Studioの値モデルは、リテラルのnull/undefinedと正しく比較できません
$shell.Reports.open{ref}()のパラメーターキーが一致しない	キーは大文字と小文字を区別し、レポートのパラメーターのName値と完全に一致させる必要があります。一致しない場合、パラメーターが未設定のまま気付かれずに描画されます
元の設定にあったフィールドが欠けた状態で、編集済みの設定をプッシュする	upsertはオブジェクト全体を置き換えるため、省略されたフィールドは削除されます。必ず最新のgetの結果を元にし、変更する項目だけを変更してください

---

編集後にpost-edit-verificationを実行し、説明文／JSON／スキーマ違反を検出してください。最終レビューにはcomponent-validatorを実行してください。