action-creator

Action Creator

ブランチ上でDatex Studioアクション（configurationTypeId=18）を作成または変更します。アクションは、エンティティのCRUDやほかのアクションを単一のコミット／ロールバック境界内で組み合わせる、サーバー側のトランザクションフローです。UIからアクションが直接呼び出されることはありません。関数がアクション呼び出しをラップし、UIからアクションへのブリッジとして機能します。

参考資料

• ../datex-studio-shared/branch-setup.md — ブランチ／接続の選択（スキル間で共通）
• references/actions.md — アクション作成の正式なリファレンス：ファイル構造、ランタイムグローバル、呼び出し規約、エラー処理ルール、事前チェックリスト
• ../datex-studio-conventions/file-format.md — configurationTypeId の一覧とTypeScript式のエンコード規則
• ../datex-studio-conventions/naming-conventions.md — _action インジケーターと -footprintFlow.json ファイルのサフィックスの非対称な命名規則
• ../datex-studio-runtime/runtime-globals.md — アクションコードで使用できる、プラットフォームが注入するグローバル変数（$flow、$flows、$datasources、$api など）
• ../datex-studio-runtime/calling-conventions.md — 呼び出し元から呼び出し先への階層の全組み合わせ（UIからアクションを直接呼び出すことはできず、アクションから関数を呼び出すこともできません）
• ../function-creator/references/functions.md — 非トランザクション型の代替手段とUIブリッジ
• ../datasource-creator/references/datasources.md — アクション階層のデータソースターゲット（-footprintDatasource.json）
• ../component-wiring-check/references/component-wiring.md — アクション呼び出し元に適用される configParameters の契約 　

依存関係

• requirements-gathering スキル — 会話のコンテキストに要件概要がまだない場合、その作成のために呼び出されます
• function-creator スキル — UI関数（UIからアクションへのブリッジ）がまだない場合、または要件が実際には非トランザクション型の場合（アクションか関数かを判断する際は関数が適しています）に呼び出されます
• datasource-creator スキル — アクションに必要な -footprintDatasource.json（FPDS）がブランチにまだない場合に呼び出されます
• component-wiring-check スキル — プッシュ前に、アクション呼び出し元の configParameters とターゲットの inParams の契約を監査するために呼び出されます
• backend-test-creator スキル — アクションを対象とするmochaテストスイートを作成する場合に呼び出されます（アクションを場当たり的なテストハーネスとして誤用するのではなく、こちらが適切な方法です）
• impact-analysis スキル — 既存アクションの inParams／outParams を変更する場合に呼び出されます（シグネチャの破壊的変更を検出します）

CLIのライフサイクル

アクションの作成には dxs configuration を使用します。これは、すべてのプラットフォーム設定タイプに対応する汎用CRUDプリミティブです。dxs action サブコマンドやフィールド単位のパッチ適用はありません。JSON本文全体を作成する（または取得して抽出する）かたちで編集し、全体をプッシュして戻します。CLIでのタイプ識別子は footprintflow（小文字。ConfigurationEndpoints.normalize_type の出力と一致）であり、footprintFlow ではありません。

新しいアクションを作成する：

# 1. Build body.json from scratch (see references/actions.md → Minimal Valid Skeleton)
# 2. Validate — gates the push. Exit 1 = errors found (read validation_errors, fix, re-run), not a broken CLI
dxs configuration validate footprintflow -b <branchId> -D body.json
# 3. Create
dxs configuration upsert footprintflow -b <branchId> -D body.json

既存のアクションを編集する：

# 1. Fetch — note the envelope wrapper
dxs configuration get footprintflow <configId> -b <branchId> -O envelope.json
# 2. EXTRACT THE INNER BODY (round-trip footgun guard — see "Round-trip rule" below)
jq .json envelope.json > body.json
# 3. Edit body.json
# 4. Validate — gates the push. Exit 1 = errors found (read validation_errors, fix, re-run), not a broken CLI
dxs configuration validate footprintflow -b <branchId> -D body.json
# 5. Push
dxs configuration upsert footprintflow -b <branchId> -D body.json

ラウンドトリップのルール（重要）

既存の設定を編集する場合、envelope.json を直接 dxs configuration upsert にパイプしてはいけません。設定内容が警告なく破損します。上記の修正後の手順（編集前に jq で内部の .json を抽出すること）は、あらゆるラウンドトリップで必須です。標準的なラウンドトリップと根本原因となったバグについては、../datex-studio-shared/configuration-roundtrip.md を参照してください。

このルールは、アクションの場合は特に重要です。アクションの JSON には code フィールドが２つあります。Datex Studio が実行するランタイムフィールドは nodes[0].stepConfig.executeCodeConfig.code です。最上位の action['code'] は非正規化されたミラーです。一方だけに書き込むと、grep では検出できませんが、ランタイムが壊れます。references/actions.md → 事前チェックリスト項目 5 を参照してください。

ワークフロー

[Phase 1: Setup + Requirements]
Follow branch-setup.md for branch/connection selection
        |
[requirements brief in context?]
  +-----+-----+
  |            |
 YES          NO -> invoke `requirements-gathering`
  |            |
  +-----+------+
        |
[Phase 2: Action vs Function decision]
Consult references/actions.md → "Purpose & When to Use":
  - transactional / entity CRUD / FPDS access -> action
  - pure read/transform / UI-facing / no atomicity -> function
If function -> invoke `function-creator` instead and stop here.
If action but UI needs to invoke it -> the UI calls a function
that wraps the action; invoke `function-creator` for the wrapper
in addition to authoring this action.
        |
[Phase 3: Author action body]
Build body.json:
  - File shape (configurationTypeId=18, apiSettingName=FootprintApi,
    referenceName ends _action, file suffix -footprintFlow.json)
  - Step graph (ExecuteCodeActivity in nodes[0])
  - inParams/outParams with FULL fat parameter-descriptor boilerplate
  - code string with \r\n line endings inside the JSON
  - Error handling: every try/catch either format-and-rethrows
    or is REMOVED. Bare swallows leave the transaction unresolved
    and surface elsewhere as "Transaction must begin first".
  - $datasources.* targets FPDS only; no $db; no $apis
  - Invoke `datasource-creator` if an FPDS dependency is missing
  - Invoke `component-wiring-check` to audit callers' configParameters
        |
[Phase 4: Validate + push]
dxs configuration validate footprintflow -b <branchId> -D body.json
        |
   +----+----+
   |         |
  CREATE   MODIFY-EXISTING
   |         |
   |         use the corrected round-trip
   |         (get -O envelope -> jq .json -> body)
   |         |
   |         if inParams/outParams changed:
   |           invoke `impact-analysis`
   |         |
   +----+----+
        |
        v
dxs configuration upsert footprintflow -b <branchId> -D body.json
   (upsert creates or updates by referenceName — one command for both)
        |
[Phase 5: Verify in Studio (optional)]
Exercise the action via its wrapping function (or via a
backend-test-creator mocha suite). Watch for delayed
"Transaction must begin first" symptoms in unrelated flows
— that's the silent-swallow signature.
        |
[invoke `post-edit-verification`; then `component-validator`]

フェーズの詳細

フェーズ 1：セットアップと要件

1. ブランチと接続の選択については、../datex-studio-shared/branch-setup.md に従ってください。ブランチ ID を決めつけてはいけません。ユーザーに確認してください。
2. 会話コンテキストに要件概要がすでに存在するか確認してください（requirements-gathering または別の呼び出し元スキルによって作成されたもの）。
   • 概要がある場合 — それを使用してください。概要には、原子性の要件（操作全体をひとまとまりとしてロールバックする必要があるか）、対象となるエンティティ／データソース、アクションの呼び出し方法（関数ラッパー、別のアクション、バックエンドテスト）を明記してください。
   • 概要がない場合 — まず requirements-gathering スキルを呼び出してください。原子性に関する質問は、次のフェーズでアクションと関数のどちらを選ぶかを決めるうえで不可欠です。

フェーズ 2：アクションと関数の選択

作成に取りかかる前に、references/actions.md → 目的と用途 を確認してください。この選択は単なるスタイルの違いではありません。アクションと関数は異なる階層に属し、ランタイム機能も互換性がありません。

次の場合はアクションを選択してください。

• 処理全体を一括して実行する必要がある（すべてコミットするか、すべてロールバックするエンティティへの書き込み）。
• ロジックが他のアクションまたはエンティティの CRUD を組み合わせる。
• コードが -footprintDatasource.json（FPDS）データソースにアクセスする必要がある（これらを利用できるのはアクション階層のみです）。

次の場合は、代わりに関数を選択してください。

• 処理が読み取り／変換のみである。
• 呼び出し元が UI である（UI からアクションを直接呼び出すことはできません。../datex-studio-runtime/calling-conventions.md を参照してください）。
• トランザクション境界が不要である。

答えが「関数」の場合は、ここでの作業を止めて function-creator を呼び出してください。答えが「アクション」でも、UI から起動する必要がある場合は、関数も必要です。UI が関数を呼び出し、その関数が $apis.<Package>.FootprintApi.extendedActions.<action_name>({ ... }) を使ってアクションを呼び出します。ここでアクションを作成し、ラッパーの作成には function-creator を呼び出してください。

フェーズ 3：アクション本体を作成する

references/actions.md → Minimal Valid Skeleton のスケルトンから body.json を作成します。主なポイント：

1. ファイルの基本事項。 configurationTypeId: 18。apiSettingName: "FootprintApi"。referenceName は _action で終わります（例：update_task_status_action）。非対称な命名規則：ファイルの接尾辞は -footprintFlow.json です（-action.json ではありません）。_action の識別子は referenceName にのみ含まれます。さらに、共通チェック（../datex-studio-conventions/universal-checklist.md）も適用されます。references/actions.md → File Location & Naming および ../datex-studio-conventions/naming-conventions.md を参照してください。

2. inParams / outParams の定型部分。 各エントリには、完全なパラメータ記述子（14 個のフィールド）を使用します。省略はできません。フィールドの不足は、インポートが拒否されるよくある原因です。正確な形式については、Minimal Valid Skeleton を参照してください。

3. code 文字列。 ステップグラフは通常、nodes[0] にある単一の ExecuteCodeActivity です。JSON 内では、改行が \\r\\n としてエスケープされています（ \r\n にデコードされます）。埋め込みコードを編集する場合は、単純な文字列置換より Python の json.load / json.dump を使用してください。

4. アクション JSON には code フィールドが 2 つあります。実行されるのはネストされた方だけです。 ランタイムフィールドは nodes[0].stepConfig.executeCodeConfig.code です。トップレベルの action['code'] は非正規化されたミラーです。ここだけに書き込んでもランタイムには反映されませんが、json.load や grep ではファイルが正しく見えます。再パッキング時は両方のフィールドに書き込み、一致することをアサートしてください。references/actions.md → Pre-Flight Checklist item 5 を参照してください。

5. エラー処理はトランザクションの成否を左右します。 アクションはトランザクション内で実行されます。エラーを黙って握りつぶすと、トランザクションが未解決のままになります。その結果、次に無関係なアクションを呼び出した際に、誤解を招く "Transaction must begin first" が発生します。これはアクションにおける最も一般的なバグです。

   ルール：

   • 価値を加えない限り、例外を捕捉しないでください。 エラーを握りつぶすだけ、または何もせず再スローするだけの try/catch は、try/catch がない場合より明らかに悪いため、削除して例外を伝播させてください。
   • 捕捉する場合は、情報を付加して再スローしてください。 試みていた処理と、関係するキー／IDをメッセージに追加する場合に限って捕捉し、その後 throw new Error(...) を実行してください。

   // Good — enriches with context and rethrows
   try {
     await $flows.Utilities.crud_update_entity({ entity: 'Tasks', keys, properties });
   } catch (e) {
     throw new Error(`Failed to update task ${keys[0].value}: ${e.message}`);
   }
   
   // Bad — swallows; transaction never closes; next action throws "Transaction must begin first"
   try { await $flows.Utilities.crud_update_entity(...); } catch (e) { /* nothing */ }
   
   // Bad — pointless rewrap; just delete the try/catch
   try { await $flows.Utilities.crud_update_entity(...); } catch (e) { throw e; }
   

   "Transaction must begin first" エラーを診断する際、原因はエラーを投げたアクションにあることはほとんどありません。別のコードパスでエラーを握りつぶした、先行するアクションにあります。最初の診断手順として、ブランチ上にあるその機能のアクションを（impact-analysis / dxs source explore を使って）すべて洗い出し、それぞれに何も処理しない catch ブロックがないか確認してください。

6. code 文字列内でのティア準拠。 別のアクションを呼び出すには $flows.<Package>.<action_name> を使用します。$datasources.<Package>.<name>.get({...}) は FPDS（-footprintDatasource.json）に対してのみ使用してください。アクションから -datasource.json を呼び出すのは、ティアをまたぐ違反です。アクションでは $db を使用できません（function ティア専用です）。アクションから $apis を使用することはまれです（function から action への呼び出しで使うものです）。../datex-studio-runtime/runtime-globals.md および ../datex-studio-runtime/calling-conventions.md を参照してください。

7. FPDS 依存関係が不足している場合、 アクションをプッシュする前に datasource-creator を呼び出して追加してください。

8. 呼び出し元の契約を監査する。 このアクションの呼び出し元はすべて、完全な configParameters 契約を宣言する必要があります。このアクションで宣言するすべての inParam は、未使用であっても value: null を設定して呼び出し元に含めます。プッシュ前に component-wiring-check を呼び出し、参照契約を監査してください。../component-wiring-check/references/component-wiring.md を参照してください。

フェーズ 4：検証してプッシュする

# Validate the body locally against the branch. Exit 1 = validation found errors
# (read validation_errors, fix body.json, re-run) — not a broken CLI. Do not push on exit 1.
dxs configuration validate footprintflow -b <branchId> -D body.json

# For a new action
dxs configuration upsert footprintflow -b <branchId> -D body.json

# For modify-existing (round-trip — never skip the jq extract)
dxs configuration get footprintflow <configId> -b <branchId> -O envelope.json
jq .json envelope.json > body.json
# ... edit body.json ...
dxs configuration upsert footprintflow -b <branchId> -D body.json

既存のアクションで inParams / outParams を変更する場合は、プッシュする前に impact-analysis スキルを実行して、すべての呼び出し元を洗い出してください。同じ編集パスで各呼び出し元（関数、その他のアクション、バックエンドテスト）を調整するか、破壊的変更についてユーザーから明示的な承認を得てください。

検証では、必須フィールドの不足、不正なパラメーター記述子の形式、参照エラーをプッシュ前に検出できます。サイレントに例外を握りつぶすケースや "Transaction must begin first" のような問題は検出できません。これは動作上の問題であり、実行時にのみ発生します。プッシュする前に、references/actions.md → 事前確認チェックリストを確認してください。特に、例外を握りつぶさない try/catch の項目が重要です。

フェーズ 5：Studio で検証する（任意）

通常の呼び出し経路でアクションを実行します。

• ラッパー関数経由（UI ブリッジ） — 関数をトリガーする画面を開き、設計どおりにアクションがコミット／ロールバックされることを確認します。
• 別のアクション経由 — オーケストレーションを行うアクションのフローから呼び出し、複合トランザクションが成功するか、アトミックにロールバックされることを確認します。
• mocha スイート経由 — backend-test-creator を使って作成します。アクションをその場限りのテストハーネスとして不適切に利用する代わりに、こちらを使用してください。

関係のない場所で、遅れて現れる "Transaction must begin first" の症状が下流のフローに発生していないか確認します。これはサイレントに例外を握りつぶした場合の兆候です。見つかった場合は、フェーズ 3 のステップ 5 に戻り、直前に編集したアクション（および、それが組み合わせているアクション）の try/catch ブロックを監査してください。

実行中のアプリを利用できない場合は、設定を再取得し（修正済みの jq .json 抽出パターンを使用）、body.json と差分を比較してプッシュが反映されたことを確認します。

事前確認チェックリスト

プッシュする前に、references/actions.md → 事前確認チェックリストの全項目を確認してください。簡易版は次のとおりです。

1. 非対称な命名。 ファイルのサフィックスは -footprintFlow.json です。referenceName の末尾は _action です。両者は異なるため、統一しないでください。
2. トップレベルの定数。 configurationTypeId: 18、apiSettingName: "FootprintApi"、空ではない 100 文字以下の description、設定済みの accessModifier。
3. すべての inParams/outParams エントリで、パラメーター記述子の完全な定型項目を使用する — 14 フィールドをすべて含め、省略しないでください。
4. code の行末は、デコード後の文字列内で \r\n にする（JSON レイヤーでは \\r\\n にエスケープします）。
5. 両方の code フィールドを書き込み、内容を一致させる — トップレベルのミラーと nodes[0].stepConfig.executeCodeConfig.code は一致している必要があります。実行されるのはネストされた方だけです。
6. すべての $datasources.* 呼び出しは FPDS を対象にする（-footprintDatasource.json）。$db.* は使用しないでください（関数層専用です）。
7. すべての try/catch で、形式を整えて再スローするか、ブロックを削除する。例外を握りつぶしたり、単独で throw e したりしないでください。これが最も重要なルールです。
8. 呼び出し元で完全な configParameters コントラクトを宣言する — このアクションが宣言するすべての inParam について、未使用のものも含め、呼び出し元にエントリを追加し、value: null を設定します。component-wiring-check で監査してください。

よくある間違い

間違い	修正方法
エラーを握りつぶす、または何もせず再スローする try/catch	ブロックを削除します。トランザクションは開いたままになり、次の無関係なアクションで "Transaction must begin first" がスローされます。コンテキストを付けて整形し、再スローする場合に限り、エラーをキャッチします。
"Transaction must begin first" の原因を、エラーをスローしたアクションから調べる	バグはほぼ常に上流にあります。別のコードパスで、先行するアクションがエラーを握りつぶしています。impact-analysis を使って、そのブランチにある機能のアクションを列挙し、それぞれに何もせずエラーを握りつぶす catch ブロックがないか確認します。
ファイル名が *-footprintFlow.json ではなく *-action.json になっている	非対称な命名規則です。_action の識別子は referenceName にのみ含め、ファイルのサフィックスは -footprintFlow.json のままにします。
アクションコードから $datasources 経由で -datasource.json を呼び出す	階層をまたぐ違反です。アクション階層から参照できるのは -footprintDatasource.json（FPDS）のみです。必要な場合は datasource-creator を使って FPDS バリアントを追加します。
アクションコードから $db.* を呼び出す	$db は関数階層専用です。読み取り処理を関数に移し、ラッパー関数からその関数を呼び出します。
nodes[0].stepConfig.executeCodeConfig.code を更新せず、トップレベルの action['code'] ミラーだけを書き換える	ランタイムには反映されません。ランタイムはネストされたフィールドを実行します。両方を書き換え、一致することを検証します。
UI フローからアクションを直接呼び出そうとする	UI からアクションは呼び出せません。アクションをラップする関数を作成し、UI からその関数を呼び出します。ラッパーには function-creator を呼び出します。
dxs configuration get -O envelope.json の出力をそのまま dxs configuration upsert -D envelope.json に渡す	設定内容が気付かないうちに破損します。編集前に必ず jq .json envelope.json > body.json を実行します。上記の「ラウンドトリップのルール」を参照してください。
簡略化した inParams／outParams 記述子を使う（objectTypeDef、isCollection などを省略する）	インポート時に拒否されます。パラメーター記述子の定型部分は14フィールドあり、省略はできません。スケルトンの完全な形式を使います。
description が100文字を超える	SQL 列の上限により、プッシュ時の検証に失敗します。短くしてください。
呼び出し元を確認せず、既存のアクションの inParams／outParams を変更する	すべての呼び出し元が、気付かないうちに、または明示的なエラーとともに破損します。まず impact-analysis を呼び出し、同じ編集で呼び出し元を整合させます。

編集後は post-edit-verification を呼び出して、description／JSON／スキーマの違反を検出します。最終レビューには component-validator を呼び出します。