footprint-workflows

Footprint Workflows

ブランチ上で、Datex Studio のフットプリントワークフロー（configurationTypeId: 23）を作成または変更します。これは、Footprint プラットフォームが独自の処理における名前付き拡張ポイント（エンティティのステータスが確定する前、カートン化中、割り当てを計画中、ロケーションを推奨中など）で呼び出す、ローコードの TypeScript 実装です。従来の XAML「Datex Workflow」アクティビティに代わる、最新の実装です。スロット、GUID、入出力のコントラクトはプラットフォームが管理し、本体はユーザーが作成します。

参照資料

• ../datex-studio-shared/branch-setup.md — ブランチ／接続の選択（すべてのスキルで共通）
• references/footprint-workflows.md — 権威あるリファレンス：本体の形式、スロットバインドと workflowsMetadata の検出、固定パラメーターのコントラクト、スロットごとのフィールドの内訳、拡張ポイントのカタログ、コードパターン、CLI のライフサイクル、事前確認チェックリスト
• ../datex-studio-shared/configuration-roundtrip.md — get -O envelope → jq .json → upsert -D のラウンドトリップと、それによって回避できるサイレントワイプのバグ
• ../datex-studio-conventions/file-format.md — configurationTypeId の一覧、コード文字列の編集ルール、return; と outParams のルール
• ../datex-studio-conventions/naming-conventions.md — _workflow サフィックスの推奨；バックエンドの型は表示名のルールに従いません
• ../datex-studio-conventions/universal-checklist.md — すべてのコンポーネントが満たす必要のある共通チェック
• ../datex-studio-runtime/calling-conventions.md — 実行階層のルール；ワークフローはアクション階層で実行されます（$flows 経由でアクションを呼び出し、fpds を読み取り、$db は使用せず、関数も使用しません）
• ../datex-studio-shared/flow-code-patterns.md — $utils.isDefined、日付のデフォルト値設定、その他のフローコードの慣用パターン
• ../action-creator/references/actions.md — アクションはワークフロー本体が呼び出すディスパッチ先であり、Footprint サーバーと同じ階層で実行されます
• ../datasource-creator/references/datasources.md — ワークフローが読み取る fpds_* フットプリントデータソース（アクション階層）

依存関係

• requirements-gathering スキル — コンテキスト内に要件概要がまだない場合に、それを作成するために呼び出します（どのスロットか、カスタム動作は何か、何にディスパッチするか、どのパッケージか）。
• action-creator スキル — ワークフロー本体がディスパッチする パッケージアクション を作成するために呼び出します。ワークフローノードは薄いディスパッチャーにとどめ、実際のロジックはアクションに配置します（同じ Footprint サーバー階層）。
• function-creator スキル — ディスパッチされるロジックを、アクションの背後にラップした関数として表現するほうが適切な場合に呼び出します（ワークフローから関数を直接呼び出すことはできません）。
• datasource-creator スキル — ワークフローが fpds_* フットプリントデータソースを通じて設定／状態を読み取る場合に呼び出します。
• type-definition-creator スキル — ディスパッチ先にパッケージのインターフェース／列挙型が必要な場合に呼び出します（FootPrintWorkflow.* の入力／結果型はプラットフォームが所有し、作成するのではなく contexts から読み取ります）。
• impact-analysis スキル — 他のコードが依存しているワークフローを変更する前、またはディスパッチ先のアクション／データソースの名前を変更する前に呼び出します。インライン検索ではなく、$flows.<Package>.<action> の呼び出し箇所を追跡します。

CLI のライフサイクル

ワークフローの作成には dxs configuration を使用します。これは、すべてのプラットフォーム設定タイプに対応する汎用的な CRUD プリミティブです。dxs workflow サブコマンドは存在しません。また、フィールド単位のパッチ適用もできません。JSON 本文全体を作成する（または取得して抽出する）必要があります。編集後、全体を CLI に戻します。CLI のタイプ識別子は footprintworkflow（小文字で、ConfigurationEndpoints.normalize_type の出力と一致）で、configurationTypeId: 23 に対応します。PublishedMain の設定は readonly: true のため、フィーチャーブランチで作成してください。

新しいワークフロー — メタデータ API からスロットを特定し、新しい GUID を割り当てます（既存のワークフローを置き換える場合は、代わりにその GUID を再利用してください。手順 2 を参照）：

# 1. Discover the slot: id (= workflowDefinitionId), name, exact inParams/outParams
dxs api GET "/footPrintApiConnections/byName/<connectionName>/workflowsMetadata?applicationId=<branchId>" --raw -O meta.json
jq '.workflowsMetadataJson.workflowDefinitions[] | select(.name=="Cartonization")' meta.json
# 2. Generate a fresh workflowGUID for this new config (new capability; you point callers at it).
#    Superseding a legacy workflow on this slot? Reuse ITS GUID instead so existing callers keep working.
python3 -c "import uuid; print(uuid.uuid4())"
# 3. Build body.json: apiSettingName + workflowDefinitionId/Name (step 1) + your fresh GUID,
#    the slot's inParams/outParams verbatim, configurationTypeId:23, id:0, your referenceName/title/description/code
# 4. (Optional) read Input/result field shapes — contexts OR meta.json `types`
dxs configuration contexts footprintworkflow -b <branchId> -D body.json
# 5. Validate, THEN upsert — these are two steps, not one. Validate exits 1 when it finds
#    errors (read validation_errors, fix body.json, re-run); do not run the upsert on exit 1.
dxs configuration validate footprintworkflow -b <branchId> -D body.json
dxs configuration upsert  footprintworkflow -b <branchId> -D body.json

既存のワークフローを編集する場合（ラウンドトリップ — jq による抽出を決して省略しないでください）：

dxs configuration get footprintworkflow <configId> -b <branchId> -O envelope.json
jq .json envelope.json > body.json          # EXTRACT THE INNER BODY (round-trip footgun guard)
# ... edit nodes[0].stepConfig.executeCodeConfig.code ...
dxs configuration validate footprintworkflow -b <branchId> -D body.json   # exit 1 = errors found; fix, do not push
dxs configuration upsert  footprintworkflow -b <branchId> -D body.json

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

envelope.json を直接 dxs configuration upsert にパイプで渡さないでください。設定内容が気付かないうちに破棄されます（エンベロープには id／jsonString／version／…が含まれますが、upsert -D はこれらを想定していません）。必ず先に jq .json envelope.json > body.json を実行してください。エンベロープには application.applicationDefinition 内の Azure アプリ登録シークレットも含まれています。jq .json による抽出ではこれらが除外されます。envelope.json をコミットしないでください。../datex-studio-shared/configuration-roundtrip.md を参照してください。

ワークフロー

[Phase 1: Setup + Requirements]
Follow branch-setup.md for branch/connection selection (feature branch — main is readonly)
        |
[requirements brief in context?]
  YES -> use it     NO -> invoke `requirements-gathering`
        |
[Phase 2: Identify the platform slot]
Pick the extension point (Cartonization, Entity Status Change (Before Commit),
Allocation Strategy, Recommend* , Barcode Parser, ...). Consult
references/footprint-workflows.md -> Extension-Point Catalog.
If nothing in the platform *calls* the slot -> a workflow config is inert; stop.
        |
[Phase 3: Bind to the slot]
Pull the workflowsMetadata API for the connection/branch -> copy the slot's
id (=workflowDefinitionId), name, and inParams/outParams VERBATIM. Never
invent the id/name. workflowGUID is NOT in the metadata — it is the code callers
pass: generate fresh for a NEW workflow, preserve it on edits, and reuse the
legacy GUID when shipping a drop-in replacement for an existing workflow.
        |
[Phase 4: Author the body]
Build body.json:
  - Slot binding (Phase 3): apiSettingName + workflowDefinitionId/Name +
    your workflowGUID + configurationTypeId:23 + start:"step1"
  - Fixed param contract: single Input: FootPrintWorkflow.<Slot>InputBaseWL;
    out-params exactly as the slot dictates (or [] for before-commit mutation)
  - Single ExecuteCodeActivity node; code is a THIN DISPATCHER to package
    actions ($flows.<Pkg>.<action>) and fpds reads; map results into
    $flow.outParams; action-tier rules (no $db, no functions)
  - id:0, accessModifier:public, description <=100 chars, vars/events null
        |
[Phase 5: Discover types + validate]
dxs configuration contexts footprintworkflow -b <branchId> -D body.json
  -> confirm $types.FootPrintWorkflow.<X>InputBaseWL + result fields you use
dxs configuration validate footprintworkflow -b <branchId> -D body.json
        |
[Phase 6: Push]
   CREATE -> dxs configuration upsert footprintworkflow -b <branchId> -D body.json
   MODIFY -> get -O envelope -> jq .json -> edit -> upsert (round-trip)
        |
[Phase 7: Verify (optional)]
Exercise the slot in the running platform; confirm the workflow is invoked and
the result/mutation lands. Re-fetch (jq .json) and diff against body.json.
        |
[invoke `post-edit-verification`; then `component-validator`]

フェーズの詳細

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

1. ../datex-studio-shared/branch-setup.md に従ってください。ブランチ ID を推測しないでください。ユーザーに確認してください。フィーチャーブランチで作成してください。PublishedMain のワークフロー設定は readonly: true です。
2. コンテキストに要件の概要があるか確認してください。概要では、対象のプラットフォームスロット、カスタム動作、ディスパッチ先のパッケージアクション／データソース、対象パッケージを明確にする必要があります。概要がない場合は、requirements-gathering を実行してください。

フェーズ 2：プラットフォームスロットを特定する

Footprint ワークフローは、Footprint プラットフォームがそのスロットを呼び出す場合にのみ実行されます。references/footprint-workflows.md → Purpose & When to Use および Extension-Point Catalog を参照してください。目的の動作が名前の付いたワークフロースロットのいずれかによってトリガーされない場合、これは適切なコンポーネントタイプではありません。必要なのは通常のアクション／関数／データソースです。シグネチャを自分で設計する必要がある場合は、ワークフローではなく関数／アクションです。

フェーズ 3：スロットにバインドする

スロットへのバインドには、独立した 2 つの要素があります。

1. スロットの識別情報とシグネチャ（プラットフォームから取得）。 Footprint の接続とブランチを指定して、workflowsMetadata API を取得します。

   dxs api GET "/footPrintApiConnections/byName/<connectionName>/workflowsMetadata?applicationId=<branchId>" --raw -O meta.json
   jq '.workflowsMetadataJson.workflowDefinitions[] | {id, name, inParams, outParams}' meta.json
   

   スロットの id を workflowDefinitionId に、name を workflowDefinitionName にコピーし、inParams／outParams は一字一句そのまま使用します。<connectionName> には実際の Footprint 接続（例：DSV）を指定します。apiSettingName の値を指定するのではありません。apiSettingName には、ブランチの Footprint 設定から取得した値を設定します。id／name をでっち上げないでください。
2. workflowGUID（呼び出し元が渡すコード）。 これはメタデータに含まれないため、カタログでは値が定まりません。ただし呼び出し元が値を指定します。この値は ProcessingStrategyWorkflowCode／AllocationStrategyWorkflowId としてサーバーに渡され、スロットで実行する実装を選択します。まったく新しいワークフローの場合は新しい v4 UUID を生成し（python3 -c "import uuid; print(uuid.uuid4())"）、呼び出し元をその値に設定してください。編集時は既存の GUID を変更せずに保持してください（jq .json によるラウンドトリップで保持されます）。呼び出し元を変更せず、既存の実装をそのまま置き換える設定の場合は、既存の GUID を再利用してください。編集時に GUID を再生成しないでください。

フェーズ 4：本文を作成する

references/footprint-workflows.md → 最小限の有効なスケルトンを基にbody.jsonを作成します。主なポイント：

1. ファイルの基本事項は、以下の事前チェックリストと共通チェックリストに従います：configurationTypeId: 23、id: 0、description は 100 文字以下、accessModifier を設定し、パッケージは機能に合わせます。
2. パラメーターの契約はプラットフォームのものであり、独自のものではありません。 インパラメーターはFootPrintWorkflow.<Slot>InputBaseWL型のInputひとつだけとします。アウトパラメーターはスロットの指定どおり（オブジェクトひとつ、コレクション、またはコミット前の変更の場合は[]）にします。Inputの名前を変更したり、パラメーターを追加したり、アウトパラメーターの形を変えたりしないでください。
3. ExecuteCodeActivityノードはひとつだけにします。 start: "step1"、ノードのid: "step1"、decisionConfig: nullを指定します。複数ノードのグラフも作成できますが、このライブラリでは使われていません。具体的な理由がない限り、ステップはひとつにしてください。
4. コードは薄いディスパッチャーにします。 $flow.inParams.Inputを$flows.<Package>.<action>の呼び出しとfpdsの読み取りに変換し、結果を$flow.outParams.<Name>に割り当てます。アクション層のルール：$dbは使わず、関数を直接呼び出さず、クラウドの-datasource.jsonではなくfpdsを使用します。outParamsが宣言されているスロットでは、return;だけではなくreturn $flow.outParams;を使用します。references/footprint-workflows.md → コードパターンを参照してください。
5. vars／events／fromBaseConfigurationはnullのままにします。

フェーズ 5：型を確認して検証する

dxs configuration contexts footprintworkflow -b <branchId> -D body.json
dxs configuration validate footprintworkflow -b <branchId> -D body.json

contextsは$types.FootPrintWorkflow.*のIntelliSenseサーフェスを返し、flowContextは宣言したシグネチャを型付きIFlowとしてエコーします。これは、$flow.inParams.Input／$flow.outParams.*がスロットの型として解決されるかを手早く確認する方法です。参照するすべてのフィールドが存在することを確認してください（プラットフォームの型を独自に作成しないでください）。必要に応じて、次の3つの確認元を使います（references → 型サーフェスの確認を参照）：

• FootPrintWorkflow.*プラットフォーム型（Input／結果の形）— contexts、またはworkflowsMetadata APIのtypes配列（構造化JSONで、より簡単に検索できます）。
• ディスパッチコードで使う**$types.<Package>.*パッケージ型**（例：$types.Utilities.e_awi_scopes.Cartonization）— dxs configuration nomenclature -b <branchId>（--package／--kind enum／--searchで絞り込みます。列挙型のメンバーはconstantValuesに表示されます）。

validateは構造上のエラーや必須フィールドのエラーを検出しますが、誤ったスロットのバインド（workflowDefinitionId／名前）、スロットと一致しないシグネチャ、アクション層の違反は検出しません。これらについては、事前チェックリストを確認してください。

フェーズ 6：プッシュする

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

フェーズ 7：確認する（任意）

稼働中のプラットフォームでスロットを実行します。エンティティのステータス変更／カートン化／割り当て／ロケーション推奨をトリガーし、ワークフローが呼び出され、結果またはコミット前の変更が意図どおりに反映されることを確認してください。アプリを利用できない場合は、設定を再取得し（jq .jsonで抽出）、body.jsonとの差分を確認して、プッシュが反映されたことを確かめてください。

事前チェックリスト

references/footprint-workflows.md → 事前チェックリストの全項目を確認してください。簡易版：

1. configurationTypeId: 23；慣例的なサフィックスは -footprintWorkflow.json。
2. スロットのバインドが正しい — workflowDefinitionId と workflowDefinitionName は workflowsMetadata カタログからコピーし、apiSettingName はブランチの Footprint 設定と一致させます。
3. workflowGUID が正しい — 新しい v4 UUID（新規ワークフローの場合。呼び出し元も参照先を変更）、既存の値をそのまま維持（編集の場合）、またはレガシーワークフローの GUID（意図的な差し替えの場合）。編集時に再生成してはいけません。
4. パラメーターの契約がスロットと一致 — スロットの入力型（通常は FootPrintWorkflow.<Slot>InputBaseWL）を指定した単一の Input；出力パラメーターはスロットの指定どおり（または []）。
5. description は空でなく、100 文字以下； accessModifier を設定；新規作成の場合は id: 0。
6. ExecuteCodeActivity ノードは 1 つのみ； start はその id を指し；vars／events／fromBaseConfiguration は null。
7. アクション層のコード要件を満たす — $flows.<Pkg>.<action>（関数や $db は使わない）、fpds による読み取り、$types.FootPrintWorkflow.*、$utils.isDefined；outParams が宣言されている場合は return $flow.outParams;。
8. 型を確認 — contexts またはメタデータの types と照合します。
9. ブランチに対して検証済み。

よくある間違い

間違い	修正方法
workflowDefinitionId／workflowDefinitionName を独自に作成、または不一致のまま使用	workflowsMetadata API からスロットの id／name と inParams／outParams を取得し、そのままコピーします。誤った ID と名前の組み合わせでも検証は通りますが、ワークフローはバインドされません。
編集時に workflowGUID を再生成、または無関係な設定からコピー	GUID はこのワークフローを選択するために呼び出し元が渡す値です（スロットのバインドには使用されません）。新規ワークフローには新しい v4 UUID を使用し（python3 -c "import uuid; print(uuid.uuid4())"）、編集時は変更せず維持します。GUID のコピーが正しいのは、その GUID を所有するワークフローの差し替えの場合のみです。
Input の名前を変更、入力パラメーターを追加、または出力パラメーターの形状を変更	シグネチャはスロットが定義します。単一の Input: FootPrintWorkflow.<Slot>InputBaseWL と、スロットで指定された正確な出力パラメーター（または []）を維持します。不一致でも検証は通りますが、呼び出しが失敗します。
Input／結果のインターフェースを手書き	dxs configuration contexts footprintworkflow -D body.json を実行して実際の形状を確認し、$types.FootPrintWorkflow.* を参照します。
ワークフローから関数を呼び出す、または $db を使用	アクション層では、$flows.<Pkg>.<action> 経由でアクションを呼び出します。関数や $db のロジックはアクションでラップし、クラウドデータソースではなく fpds を使用します。
outParams が宣言されたスロットで return; のみを記述	return $flow.outParams; を使用します。return; のみでは生成された本体が壊れます。Validate では検出されず、Preview で検出されます。
get -O envelope.json の出力をそのまま upsert -D に渡す	先に jq .json envelope.json > body.json を実行します。エンベロープを渡すと内容が上書きされ、シークレットも含まれます。
最小化された code 文字列に対して検索・置換を直接実行	Python の json.load／json.dump を使って編集し、\r\n で結合して構築します。周囲の JSON の構造は変更しないでください。
ノード内に複雑なビジネスロジックを直接記述	ノードはパッケージのアクションに処理を振り分けるだけの薄いディスパッチャーにします。ライブラリとの整合性が保たれ、保守しやすくなります。
PublishedMain を対象に作成	Main は readonly: true です。確認済みのフィーチャーブランチで作成してください（ID を推測しないでください）。

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