【AWS CDK】Workflow StudioのプロパティにCDKの値を動的に設定するには？

はじめに

※この記事はAWS CDK Advent Calendar 2025 10日目の記事です。

qiita.com

皆さん、Workflow Studio 使ってますか？

AWS Step Functions（以下「Step Functions」）のワークフローをGUIで編集できる、めちゃくちゃ便利なツールです。

VS Codeの「AWS Toolkit」拡張機能をインストールすれば、ローカルのVS Code上でも実行できるので、ますますStep Functionsのワークフロー作成が便利になりました。

ただ、Workflow StudioとCDKを一緒に使う場合、下記の点が問題になります。

1. Workflow StudioからCDKの値（プロパティなど）を参照できない
   • Workflow StudioとCDKは連動しているわけではない
2. Workflow StudioにCDKの動的な値（例えばCDKで作成したS3バケットのARNなど）は設定できない
   • あくまで動的な値が作成されるのはデプロイ後なので

しかしWorkflow Studioを使用していると「Workflow StudioのプロパティにCDKの動的な値を設定したい」というケースが出てきます。

今回はその「Workflow StudioのプロパティにCDKの動的な値を設定する方法」についてお話しします。

前提

Workflow Studioのワークフローファイルの拡張子は*.asl.json, *.asl.yaml, *.asl.yml の3つがありますが、この記事では *.asl.json で統一します。（他の拡張子でも記載内容はそのまま適用できます）

例えばどういうケース？

ワークフローからWeb APIリクエストを行う際に使用する「Call HTTPS APIs」アクションでは「接続ARN」として、Web APIリクエストで使用するEventBridge ConnectionのARNを指定する必要があります。*1

このEventBridge ConnectionをCDKで定義している場合、「接続ARN」にこのEventBridge ConnectionのARN（connectionArn）を設定したいのですが、先述の理由でそれができません。

ただ、これができないと

1. 一度「接続ARN」にダミーの値を設定してデプロイする
2. デプロイ後、マネジメントコンソールからEventBridge ConnectionのARNを確認する
3. 2で確認したEventBridge ConnectionのARNを「接続ARN」に設定して再度デプロイする

という3ステップが必要になり面倒なので*2、これを解決する方法はないか...というのが今回の本題になります。

解決方法

この問題の解決方法は、以下の2つです。（他にもあるかもしれませんが）

1. *.asl.json ファイルの内容をデプロイ時に置換する
2. JSONataで実行時の入力文字列を取得するようにする

1. *.asl.jsonファイルの内容をデプロイ時に置換する

Workflow Studioのワークフローの実態は *.asl.json というjsonファイルです。
つまり、このjsonファイルの内容をデプロイ時に動的に書き換えてしまえばよいわけです。

具体的には、このようなソースを記載します。（なおこの時、「接続ARN」にダミーの決め打ち値を設定しておきます）

import fs from "node:fs";  
import path from "node:path";  
import { StateMachine, DefinitionBody } from "aws-cdk-lib/aws-stepfunctions";  
import { Connection, Authorization } from "aws-cdk-lib/aws-events";  
  
// EventBridge Connectionを作成    
const connection = new Connection(this, 'Connection', {
  authorization: Authorization.apiKey(...),
});
  
// *.asl.jsonファイルを読み込み、内容を置換。
// CONNECTION_DUMMY_ARNには先ほど「接続ARN」に設定したダミーの決め打ち値を定義しておく
const stateMachineDefinition = fs
      .readFileSync(path.resolve(__dirname, "./asl/example.asl.json"), "utf8")
      .replaceAll(CONNECTION_DUMMY_ARN, connection.connectionArn);
  
// ステートマシンを定義する。
// この時definitionBodyを「DefinitionBody.fromString」とし、引数に
// 置換後の*.asl.jsonファイルの文字列を設定する。
const stateMachine = new StateMachine(this, 'StateMachine', {
      definitionBody: DefinitionBody.fromString(stateMachineDefinition),
      ...(以下略)
});

ポイントは DefinitionBody.fromString() で、これを使用する事で definitionBody の値を文字列で指定することが可能です。（大抵の定義では DefinitionBody.fromFile() で*.asl.json ファイルを読み込むことがほとんどですが）

2. JSONataで実行時の入力文字列を取得するようにする

これは使用ケースが限定されますが、「接続ARN」の値をJSONataで設定しておき、EventBridge ConnectionのARNをステートマシン実行時に受け取るように設定する...というものです。

例えばAPI Gateway経由でステートマシンを実行する場合は、以下になります。

1 「接続ARN」の値を {% $states.input.connectionArn %}と設定する

2 AwsIntegration などIntegration系クラスのリクエストテンプレート(requestTemplates)に、下記のように設定する

// import文は省略
const stateMachineIntegration = new AwsIntegration({
  service: "states",
  action: "StartExecution",
  integrationHttpMethod: "POST",
  options: {
    requestTemplates: {
      // API Gatewayにリクエストが送られたときにEventBridge ConnectionのARNをinput.connectionArnとしてStep Functionsに渡す
      "application/json": `{
        "input": `$util.escapeJavaScript({'connectionArn' : ${connection.connectionArn}})`,
        "stateMachineArn": "${stateMachineStandard.stateMachineArn}"
      }`,
    },
  }
});

ただし先述の通り、この方法は「使用ケースが限定的」「設定が少々複雑（リクエストテンプレートを設定する、など）」などの点があるため、個人的には「1. *.asl.jsonファイルの内容をデプロイ時に置換する」の方法が良いと思います。

まとめ

以上「Workflow StudioのプロパティにCDKの値を動的に設定する」方法でした。

正直、1の方法も最初は微妙かな...と思ったのですが*3、いろいろ調べた結果、現在はこの方法が一番のようです。（AWSのSAさんにも確認しました）

なおこの話に関しては、2025/11/21（金）開催の JAWS-UG CDK支部#23 札幌でもCDKしたいっしょ でも発表しておりますので、もしよろしければそちらの登壇資料も併せてご確認ください。

speakerdeck.com

では、今回はこの辺で。