1. はじめに

このドキュメントは、EC Bridge（ハブシステム）における「ステップ登録」の理解と運用を支援するための技術リファレンスです。

EC Bridgeでは、ワークフローと呼ばれる処理フローを定義し、その中で「ステップ」と呼ばれる個別の処理単位を順次実行する構造を採用しています。ステップを組み合わせることで、API連携やデータ変換、ファイル処理など多様な業務処理をローコードで実現できます。

ステップを正しく登録・設定するためには、システムの構造と設定ルール（特に 設定や ExpressionLanguage の表現形式）についての理解が必要です。

このドキュメントでは、以下の内容を網羅的に解説します：

• ステップ共通の必須項目（step_id, type, next_step_id など）
• 各ステップの 記述方法と設定例
• ExpressionLanguage の基本構文と使用例
• 代表的な処理パターン（読み取り → 変換 → API送信 など）
• 典型的なエラーと対処法
• ステップ登録手順と入力画面の補足説明

2. ステップ共通項目

各ステップには共通して定義すべき基本項目が存在します。これらはすべてのステップ定義に含まれる必要があり、ワークフローの制御・接続・説明に用いられます。

共通項目一覧

備考

• step_id は ExpressionLanguage における step_data('step_id', 'key') 形式でデータ参照する際に利用されるため、明確で簡潔な命名が望まれます。
• next_step_id は直線的なステップ接続に使われますが、branching や end_loop など構造制御ステップでは別途 「設定」 内で遷移先が定義されるため省略可能です。

3. 各ステップ別の設定仕様

begin（開始）

概要

ワークフローの最初に必ず置かれるステップで、初期データを定義します。外部から渡されたフォームデータ（form_data）を受け取り、必要に応じて initial_data により固定値を追加・上書きできます。

「設定」 構成

参照例

• step_data('begin', 'form_data.user_id') : フォーム送信された user_id
• step_data('begin', 'fixed_value') : 手動で設定された固定値

設定例

{
    "initial_data": {
      "fixed_value": "'OK'",
      "timestamp": "dateformat(now(), 'YmdHis')"
    }
}

この設定により、フォームで送られたデータと fixed_value, timestamp がマージされて次ステップに渡されます。

end（終了）

概要

ワークフローの実行を終了させるステップです。後続のステップを持たず、以降の処理は実行されません。

「設定」 構成

このステップは 「設定」 を持ちません。

設定例

{

}

この設定により、ワークフローはこのステップで終了します。

transform（データ変換）

概要

ExpressionLanguage を用いて、データの変換・加工・構築を柔軟に行うステップです。各ルールごとにキーと値、または条件分岐による cases を設定し、自由な構造を組み立てられます。

「設定」 構成

rules 配下の各ルール形式

設定例

{
    "rules": [
      {
        "key": "product.code",
        "value": "step_data(1, 'product_id')"
      },
      {
        "key": "product.upper_name",
        "value": "upper(step_data(1, 'product_name'))"
      },
      {
        "key": "product.name_hash",
        "value": "substring(sha256(step_data(1, 'product_name')), 0, 10)"
      },
      {
        "key": "product.price_total",
        "value": "step_data(1, 'retail_price') * step_data(1, 'secret_price')"
      },
      {
        "key": "product.secret_price_tag",
        "value": "'Secret: ' ~ step_data(1, 'secret_price') ~ '円'"
      },
      {
        "key": "product.type_label",
        "cases": [
          {
            "when": "step_data(1, 'product_type') == 'NORMAL'",
            "value": "'通常商品'"
          },
          {
            "when": "step_data(1, 'product_type') == 'SET'",
            "value": "'セット商品'"
          },
          {
            "when": true,
            "value": "'その他'"
          }
        ]
      },
      {
        "key": "product.description_encoded",
        "value": "base64_encode(step_data(1, 'description_for_mobile'))"
      },
      {
        "key": "product.explanation_kana_half",
        "value": "to_half_kana(step_data(1, 'explanation_for_pc'))"
      },
      {
        "key": "product.explanation_kana_full",
        "value": "to_full_kana(step_data(1, 'explanation_for_mobile'))"
      },
      {
        "key": "product.random_token",
        "value": "random('alnum', 8)"
      },
      {
        "key": "product.unique_id",
        "value": "unique('uuid', 12)"
      },
      {
        "key": "product.is_taxable",
        "value": "in_array(step_data(1, 'tax_type'), ['STANDARD', 'REDUCED'])"
      },
      {
        "key": "product.is_discounted",
        "value": "between(step_data(1, 'secret_price'), 1, 2)"
      }
    ]
}

この設定により、指定されたキーに対し、それぞれ式による動的な変換や条件分岐出力が可能になります。

出力されるデータ例（イメージ）

以下のような構造のデータが出力されます：

{
  "product": {
    "code": "P12345",
    "upper_name": "サンプル商品Ａ",
    "name_hash": "a1b2c3d4e5",
    "price_total": 1980,
    "secret_price_tag": "Secret: 990円",
    "type_label": "通常商品",
    "description_encoded": "U29tZSBkZXNj",
    "explanation_kana_half": "ｻﾝﾌﾟﾙｶｲｾﾂ",
    "explanation_kana_full": "サンプルカイセツ",
    "random_token": "f8kdP9zL",
    "unique_id": "e1f3c2d4a5b6",
    "is_taxable": true,
    "is_discounted": true
  }
}

※ 各値は式評価結果の例であり、入力値によって変動します。

mapping（構造変換）

概要

入力データを別の構造・キー名に変換するシンプルなマッピングステップです。静的なキー変更や定数の追加、ExpressionLanguage による動的変換にも対応します。

「設定」 構成

注意点

• mapping ステップは「単純なキー変換や定数挿入」に特化したシンプルなステップです。複雑なネスト構造や動的処理が必要な場合は transform ステップを利用してください。
• ドット記法（例：product.id）によるネスト構造の出力には対応していません。すべてのキーは平坦な構造として扱われます。
• 文字列を直接設定する場合、ExpressionLanguage で評価されるため常にシングルクォートで囲む必要があります。
• rules 全体を ExpressionLanguage 式で構築することも可能です（例：step_data('apicall1') など）。

設定例1：静的なマッピング（すべて文字列）

{
    "rules": {
      "user_id": "'id'",
      "user_name": "'name'",
      "user_email": "'email'"
    }
}

出力例：

{
  "user_id": "id",
  "user_name": "name",
  "user_email": "email"
}

設定例2：ELで他ステップの結果を参照

{
    "rules": {
      "product_id": "step_data('apicall2', 'product_id')",
      "status": "'OK'"
    }
}

出力例（例：apicall2 の結果が { "product_id": 12345 } の場合）：

{
  "product_id": 12345,
  "status": "OK"
}

設定例3：rules 全体を式で指定

{
    "rules": "step_data('transform1')"
}

出力例（例：transform1 の出力がそのまま流用される）：

{
  "product": {
    "code": "P12345",
    "name": "商品A"
  }
}

filter（フィルタリング）

概要

オブジェクト形式のデータから、指定したキーのみを抽出するシンプルなフィルタリングステップです。ドット記法によりネストされたキーにも対応しています。

「設定」 構成

注意点

• target は 1 レコード（連想配列）を対象とする前提です。
• filters で指定されたキーのみが出力に含まれます。
• filters によるフィルタリング処理は、配列全体ではなくオブジェクト 1 件に対して適用されます。
• filters で指定するキーには ドット記法（例：product.id）を使ってネストされた値を抽出することが可能です。

設定例：ネストされたキーの抽出

{
    "target": "step_data('get_product')",
    "filters": [
      "product.id",
      "product.attributes.size"
    ]
}

出力例：

{
  "product": {
    "id": 201,
    "attributes": {
      "size": "S",
      "color": "red"
    },
    "stock": 10
  },
  "metadata": {
    "created": "2024-01-01"
  }
}

フィルタ後の出力：

{
  "product": {
    "id": 201,
    "attributes": {
      "size": "S"
    }
  }
}

find（値の抽出）

概要

このステップは、ネスト構造を含む複雑な配列やオブジェクト内から、指定されたキーに基づき一致する値を抽出する処理を提供します。filter ステップとは異なり、find ステップは単一の要素を特定して抽出する用途に特化しています。

「設定」 構成

このステップでは、抽出元の対象と、抽出条件となるキー名を ExpressionLanguage によって指定する必要があります。

動作仕様

• target は配列またはオブジェクトとして評価される必要があります。
• 指定された key に基づいてネスト構造を辿り、該当する値を抽出します。
• 該当する値が存在しない場合、本ステップは UnprocessableEntityHttpException をスローし、ワークフローの実行が中断されます。
• 出力は一致する値そのもの、もしくは値が配列であればその配列が返却されます。

注意点

• key は ドット記法に対応しており、ネストされたデータ構造を自然に指定できます。
• target や key に記述する式は ExpressionLanguage で構築され、前段ステップの出力値などを柔軟に参照可能です。

設定例

以下は、外部ステップで取得した商品情報から、指定された色情報を抽出する例です：

{
    "target": "step_data('transform1')",
    "key": "'product.attributes.color'"
}

出力例

対象データ：

{
  "product": {
    "id": 123,
    "name": "商品ABC",
    "attributes": {
      "color": "red",
      "size": "M"
    }
  },
  "metadata": {
    "created": "2024-05-01"
  }
}

この設定で抽出される出力：

"red"

api_call（API呼び出し）

概要

HTTP API を呼び出し、外部サービスと連携するステップです。リクエストのメソッド、エンドポイント、ヘッダー、ボディを柔軟に指定でき、ExpressionLanguage を用いて動的に生成することも可能です。

「設定」 構成

注意点

• URL やヘッダー、ボディの各項目は ExpressionLanguage を用いて動的に構築可能です。
• body を省略または null にするとボディ無しで送信されます。
• Content-Type ヘッダーは自動で設定されないため、必要に応じて明示的に指定してください。
• request_type に soap を指定した場合、body は SOAP1.1 もしくは SOAP1.2 に準拠した構造で記述してください。(後述)
• response_type に xml を指定した場合、レスポンスは自動的にパースされ JSON 構造で扱えるようになります。
• response_type に soap を指定すると、レスポンスは SOAP XML を JSON に変換した構造で取得されます。
• response_encoding を指定することでレスポンスの文字化けに対応可能。ワークフロー上では指定した文字コードからUTF-8に変換されます。

設定例：JSON形式でPOST送信

{
    "method": "'POST'",
    "url": "'https://api.example.com/products'",
    "headers": {
      "Authorization": "'Bearer ' ~ step_data('auth', 'access_token')",
      "Content-Type": "'application/json'"
    },
    "body": {
      "product_id": "step_data('transform1', 'product_id')",
      "name": "step_data('transform1', 'product_name')"
    }
}

設定例：SOAP

@valueを使わないマッピングの設定
{
  "rules":
    "soap:Envelope": {
      "soap:Body": {
        "NumberToWords": {
          "ubiNum": 123,
          "@attributes": {
            "xmlns": "'http://www.dataaccess.com/webservicesserver/'"
          }
        }
      },
      "@attributes": {
        "xmlns:soap": "'http://schemas.xmlsoap.org/soap/envelope/'"
      }
    }
  }
}

@valueを使うマッピングの例
{
  "rules": {
    "soap:Envelope": {
      "@value": [
        {
          "soap:Body": {
            "@value": [
              {
                "NumberToWords": {
                  "@value": [
                    {
                      "ubiNum": 123
                    }
                  ],
                  "@attributes": {
                    "xmlns": "'http://www.dataaccess.com/webservicesserver/'"
                  }
                }
              }
            ]
          }
        }
      ],
      "@attributes": {
        "xmlns:soap": "'http://schemas.xmlsoap.org/soap/envelope/'"
      }
    }
  }
}

API呼び出しの設定
{
  "url": "'https://www.dataaccess.com/webservicesserver/NumberConversion.wso'",
  "body": "step_data(1)",
  "method": "'POST'",
  "headers": {
    "SOAPAction": "'http://www.dataaccess.com/webservicesserver/NumberToWords'",
    "Content-Type": "'application/soap+xml; charset=utf-8'"
  },
  "request_type": "soap",
  "response_type": "soap"
}

レスポンス例（自動で格納）：

{
  "status": "success",
  "code": 200,
  "data": {
    "message": "Product created successfully."
  }
}

validation（バリデーション）

概要

指定したデータに対して、各種バリデーションルールを適用して検証を行うステップです。
API呼び出しなどを伴わず、データの正当性を確認するだけの目的で利用できます。

「設定」 構成

rules 内の各項目の構成

rules では、各項目名（例: name, name_kana）ごとに以下のルールが設定できます。

動作仕様

1. target で指定したデータ をEL式として評価し、バリデーション対象の配列を取得します。
2. rules に定義された各項目に対して、以下のバリデーションを順次適用します。

• 必須項目（required）
• データ型（type）
• 文字列長さ（max_length, min_length）
• 文字列のバイト数（max_bytes, min_bytes）
• 数値範囲（max_value, min_value）
• 禁止文字（forbidden_characters）
• 正規表現（regex_pattern）
  など

1. ルールに違反した項目は、各項目ごとに 複数のエラーメッセージを配列で返却 します。

注意点

• バリデーションに失敗した場合、ワークフローは以降のステップを実行せず停止します。
• レスポンスは以下の形式で返却されます。

  {
    "response": false,
    "details": {
      "項目名": [
        "エラーメッセージ1",
        "エラーメッセージ2"
      ]
    }
  }

設定例

beginステップで受け取ったフォームデータのうち、以下のルールでバリデーションする設定の例

• 「name1の値は必須の文字列項目。最大10文字まで。日本語ラベルは『氏名』。」。input要素のname属性が’name’の要素に対してエラーメッセージを出す。
• 「name2の値は必須の文字列項目。最大10文字まで。日本語ラベルは『氏名カナ』。全角カナ・全角スペースのみ許可（正規表現: ^[ァ-ヶー　]+$）。」。input要素のname属性が’name_kana’の要素に対してエラーを出す。

{
  "target": "step_data('begin', 'form_data')",
  "rules": {
    "name1": {
      "type": "string",
      "element": "name",
      "required": true,
      "attribute": "氏名",
      "max_length": 10
    },
    "name2": {
      "type": "string",
      "element": "name_kana",
      "required": true,
      "attribute": "氏名カナ",
      "max_length": 10,
      "regex_pattern": "^[ァ-ヶー　]+$"
    }
  }
}

branching（条件分岐）

概要

このステップは、ExpressionLanguage による条件式の評価結果に応じて、次に実行するステップを動的に切り替えるための分岐制御を提供します。複数のケース（条件）を順番に評価し、最初にマッチした条件の next_step_id に制御を移します。

「設定」 構成

各ルールの構成：

動作仕様

• rules に定義された順に when の式を評価します。
• 最初に true となった条件の next_step_id に制御が移ります。
• いずれの条件も一致しなかった場合はステップエラーとなり、ワークフローは中断されます。

注意点

• 条件式には ExpressionLanguage の任意の関数や比較演算子が利用可能です。
• when: true を最後に追加することでデフォルト分岐（catch-all）として利用できます。

設定例

{
    "rules": [
      {
        "when": "step_data('check', 'status') == 'ERROR'",
        "next_step_id": "error_handler"
      },
      {
        "when": "step_data('check', 'status') == 'WARN'",
        "next_step_id": "warn_logger"
      },
      {
        "when": true,
        "next_step_id": "proceed"
      }
    ]
}

begin_loop（ループ開始）

概要

このステップはループ構造の開始点を示します。配列データに対して繰り返し処理を行うための制御構造で、end_loop ステップと対になるように設計されています。指定した配列の要素数に応じて、ループ内のステップが順次繰り返し実行されます。

「設定」 構成

動作仕様

• target で指定された配列の各要素に対して、ループ内部のステップが繰り返し実行されます。
• loop_index は自動的に管理され、step_data(step_id, key, loop_index) 形式で参照可能です。
• ループごとにスコープが切り替わり、同一ステップの出力も loop_index ごとに保持されます。
• 空配列が指定された場合は、ループ内のステップは一度も実行されずに end_loop にスキップされます。

注意点

• begin_loop ～ end_loop 間に含まれるステップは、ループ制御下でのみ有効です。
• ネストされたループは サポートされていません。入れ子構造にすると実行時エラーになります。
• target の評価結果が配列でない場合はステップエラーとなります。

設定例

{
    "target": "step_data('transform1', 'items', 0)"
}

この例では、transform1 ステップの items 配列に対して繰り返し処理を行います。

ターゲットの参照先がループの度に変わらないようにする必要があるため、step_data関数で参照するloop_indexには0を指定してください。

end_loop（ループ終了）

概要

このステップは、begin_loop ステップと対になり、ループ処理の終端を示します。対応する begin_loop の target に基づくループの実行制御を終了し、次のステップに制御を移します。

「設定」 構成

end_loop ステップには設定項目はありません。

動作仕様

• 実行時には、現在のループインデックスに応じて、次のループが必要かを自動的に判定します。
• 残りの要素がある場合は、begin_loop に制御が戻り、ループ内部を再実行します。
• 全てのループが完了した場合、end_loop ステップの next_step_id に処理が移行します。
• 対応する begin_loop が存在しない、あるいはネスト構造で重複した場合は、実行時にエラーとなります。

注意点

• end_loop の next_step_id は必須であり、ループ終了後に進むべきステップを明示する必要があります。
• このステップ単体では何も処理を行わず、ループ制御のための構文的な終端を表します。
• begin_loop ～ end_loop 間に配置されたステップは、各ループサイクルで繰り返し実行されます。

設定例

なし

{

}

session_store（一時保存）

概要

このステップは、任意のデータをワークフローセッション（ステップ間で共通利用できる一時保存領域）に保存する機能を提供します。保存されたセッションデータは、session_retrieve ステップで後続ステップから再利用可能です。

「設定」 構成

動作仕様

• 指定された key に対して、value の評価結果をセッションに保存します。
• session_retrieve ステップを使って、後続ステップでこの key に対応する値を取得可能です。
• 同一 key を重複して保存すると、上書きされます。

注意点

• セッションデータはワークフロー実行中にのみ有効で、永続化されません。
• データは JSON シリアライズ可能な形式である必要があります（文字列、数値、配列、オブジェクトなど）。

設定例

{
    "store_key": "product_data",
    "store_data": "step_data('transform1')"
}

この例では、transform1 ステップの出力を product_data というキーでセッションに保存します。

session_retrieve（復元）

概要

このステップは、session_store ステップでセッション領域に保存されたデータをワークフロー内で再利用するために取得する機能を提供します。保存されたセッションデータはステップ出力として取り出され、以降のステップで参照可能になります。

「設定」 構成

動作仕様

• 指定された retrieve_key に対応するデータをセッション領域から取得します。
• 該当データが存在しない場合はステップエラーとなります（セッション未定義エラー）。
• 正常に取得されたデータは、本ステップの出力データ（step_data）として利用可能になります。

注意点

• 対象の store_key が存在していない場合、ワークフローは例外をスローして中断されます。
• 取得したデータはそのまま次のステップで利用することができます（EL式などで step_data('retrieve_step_id') など）。

設定例

{
    "retrieve_key": "product_data"
}

この例では、product_data というキーで保存されたセッションデータを取得します。

レスポンス例（自動で格納）：

{
  "retrieved_data": {
    "product_id": "item001"
  }
}

file_read（ファイル読み込み）

概要

FileReadStep は、オーナーディレクトリ配下に存在するファイルを読み取り、ワークフローにデータを取り込むためのステップです。
読み取り対象ファイルは、directory, file, extension の組み合わせにより動的に決定され、前方一致で検索されます。
オーナーディレクトリ外のファイルにはアクセスできないよう制限されています。

「設定」 構成

動作仕様

• directory 配下から file + ‘.’ + extension に前方一致かつ拡張子一致するファイルを検索。
• 更新日時が最も古いファイルを1件だけ読み込む。
• has_header が true の場合は、先頭行をキーとしてマッピングされる。
• 読み込み件数は batch_size に制限される。
• ../ を含むなど、オーナーディレクトリを逸脱するパスは拒否される。
• 読み込みファイルの文字コードがUTF-8以外の場合は、file_encoding に読み込みファイルの文字コードを指定してください。

設定例

{
  "directory": "'read'",
  "file": "'customers'",
  "extension": "'tsv'",
  "delimiter": "','",
  "batch_size": 100,
  "has_header": true
}

file_write（ファイル書き込み）

概要

FileWriteStep は、ワークフロー内のデータをCSVやTSV形式でファイルに出力するステップです。
指定された directory, file, extension を基に出力パスを構築し、1レコードずつ追記形式で書き込みます。
ファイルが空の場合には、ヘッダー（キー名）行も自動的に出力されます。

「設定」 構成

動作仕様

• 出力ファイルパスは directory + ‘/’ + file + ‘.’ + extension で構築。
• ディレクトリが存在しない場合は作成される（ただしオーナーディレクトリ外は禁止）。
• ファイルが存在しないか、空の場合はヘッダー行が自動出力される。
• 各実行ごとに1レコードが追記される（append）。
• ../ 等の不正パス指定はすべて拒否される。

target は ExpressionLanguage により柔軟に指定可能。

設定例

{
  "directory": "'write'",             // 出力先ディレクトリ（相対パス）
  "file": "'converted'",              // ファイル名（拡張子を除く）
  "extension": "'tsv'",               // 拡張子（例: "csv", "tsv"）
  "delimiter": "'\\t'",                 // 区切り文字（例: ",", "\t"）
  "target": "step_data('transform')" // 出力対象の1レコード
}

file_compress（ファイル圧縮）

概要

FileCompressStep は、ワークフロー内で生成されたファイルを圧縮するステップです。
指定された directory, file, extension に基づいて圧縮対象ファイルを特定し、type で指定された形式（現在対応している圧縮タイプは .gz のみ）で同じディレクトリに圧縮ファイルを出力します。

「設定」 構成

動作仕様

• 圧縮対象ファイルのパスは directory + '/' + file + '.' + extension で構築。
• 圧縮後のファイルは同じディレクトリに file + '.' + extension + '.gz' の形式で出力される（例：report.csv.gz）。
• 圧縮後のファイルのパスを meta'にcompressed_file` として記録。
• オーナーディレクトリ外へのアクセスは拒否される。
• .. を含む不正なパス指定は拒否される。
• 現在は .gz のみサポート。

設定例

{
  "directory": "'exports/daily'",
  "file": "'report_20250529'",
  "extension": "'csv'",
  "type": "'gz'"
}

ftp_upload（ファイル転送）

概要

ftp_upload ステップは、ローカルディレクトリ内の指定ファイルを SFTP または FTPS 経由で外部のファイルサーバーへアップロードするためのステップです。
アップロード完了後、オプションでローカルファイルの削除も可能です。

「設定」 構成

動作仕様

1. ローカルファイル検証

• 指定された local_directory / local_file_name のパスを結合し、実在かつオーナーホーム配下であるかを検証
• .. を含むパスは拒否される

2. 外部サーバーへ接続

• 指定されたプロトコル（SFTP / FTPS）で接続を確立
• タイムアウト、ポートなども設定可能

3. ファイルアップロード

• 対象のローカルファイルをストリームで読み込み、リモートにアップロード
• リモートディレクトリが存在しない場合、自動で作成

4. メタ情報

• 実際にアップロードしたリモートパス remote_path をレスポンスメタに追加

設定例

{
  "protocol": "'SFTP'",
  "host": "'sftp.example.com'",
  "port": 22,
  "username": "'user01'",
  "password": "'pass123'",
  "timeout": 30,
  "local_directory": "'exports/202506'",
  "local_file_name": "'order_list.csv'",
  "remote_directory": "'/upload/orders'",
  "remote_file_name": "'orders_202506.csv'"
}

4. ExpressionLanguage 基礎

概要

この章では、EC Bridgeにおける ExpressionLanguage（EL）の基礎知識を体系的に解説します。ELは、ステップ設定において柔軟なデータ参照・加工・分岐処理を可能にする記述言語であり、ワークフロー定義の中核を担います。

ステップ種別ごとに step_data() などの関数を用いて、他ステップの出力を参照したり、文字列変換・数値演算・条件式評価・ランダム値生成・日付処理などを行うことができます。

基本構文

ステップデータの参照

step_data('step_id', 'key_path')

• step_id：参照対象のステップID（文字列）
• key_path：ドット記法で指定可能（例：product.name）
• loop_index を第3引数として指定することでループ中のインデックス付きデータにもアクセス可能：

step_data('step1', 'price', 2)

式の記述例

upper(step_data('transform1', 'name')) ~ '（税込）'

• ~ 演算子で文字列連結
• upper() 関数で大文字変換

現在の繰り返し回数の参照

EL式が使える箇所であれば、loop_indexのキーワードで参照できます。

Transformステップでloop_indexを参照する方法の例

{
  "rules": [
    {
      "key": "shipment_list",
      "cases": [
        {
          "when": "loop_index == 0",
          "value": "array_push(step_data('init_shipment_list','shipment_list',0),step_data('transform_shipment_data'))"
        },
        {
          "when": "loop_index > 0",
          "value": "array_push(step_data('push_shipment_data','shipment_list', loop_index - 1),step_data('transform_shipment_data'))"
        }
      ]
    }
  ]
}

4. ExpressionLanguage 関数リファレンス

各カテゴリごとに、関数の目的・引数・使用例・結果を一覧表に整理しました。

ステップ関連関数

ワークフローにおいて、他ステップの出力や実行状態を参照するための関数です。

よく使われる step_meta() キー例

文字列操作

数値操作

配列操作

使用例

array_push(step_data('1', 'items'), step_data('2'))
// => ステップ1の items 配列の末尾にステップ2のデータを追加

array_merge(step_data('1', 'a'), step_data('2', 'b'), step_data('3', 'c'))
// => ステップ1〜3の各配列を順番に結合した新しい配列を返す

count(step_data('1', 'items'))
// => ステップ1の items 配列の要素数を返す

get(step_data('1', 'user'), 'profile.email', 'unknown@example.com')
// => ステップ1の user 配列から 'profile要素のemail要素' を取得。
//    user['profile']['email'] が存在すればその値を返し、
//    存在しなければ 'unknown@example.com' を返します。

[
  {"id":1,"detail":{"level":"'A'"},"status":"'active'"},
  {"id":2,"detail":{"level":"'B'"},"status":"'inactive'"},
  {"id":3,"detail":{"level":"'C'"},"status":"'active'"},
  {"id":4,"status":"'active'"}
]

filter_by(step_data('begin'), \"get(x, 'status') == 'active'\", 'x')"
→id=1,3,4のみ抽出
filter_by(step_data('begin'), \"get(x, 'detail.level') == 'A'\", 'x')"
→id=1のみ抽出

日付操作

判定関数

変換・生成系

クエリ・XML生成

よくある記述例

{
  "rules": [
    {
      "key": "price_tax_included",
      "value": "round(step_data('1', 'price') * 1.1)"
    },
    {
      "key": "user_label",
      "value": "step_data('user', 'name') ~ '（ID:' ~ step_data('user', 'id') ~ ')'"
    },
    {
      "key": "short_hash",
      "value": "substring(sha256(step_data('1', 'email')), 0, 8)"
    }
  ]
}

注意点

• 文字列リテラルは常にシングルクォート 'value' で囲む必要があります。
• ドット記法でネストキーにアクセスする場合、存在しないキーを指定すると null になります。
• 型不一致（例：数値演算に文字列を渡すなど）には十分注意してください。

この章では ExpressionLanguage を使ったデータの取り回し・演算・制御構文を整理しました。高度な条件分岐やデータ変換処理を実現するための中核技術であるため、他のステップ設定と併せて習得しておくことが推奨されます。

5. レスポンス構造

各ステップの出力結果やメタ情報は step_data() / step_meta() を通じて参照できます。
以下に、共通およびステップ固有の meta 情報の一覧を示します。

ステップ種別ごとの追加メタ情報（step_meta）

ステップ種別に応じて、共通項目に加えて以下のような meta 情報が追加されます。これらは step_meta('step_id', 'キー名') で参照できます。

共通

api_call ステップ専用

※ http_status や origin_response はレスポンスが存在しない場合は null や空文字になります。

begin_loop ステップ専用

file_read ステップ専用

write_file ステップ専用

file_compress ステップ専用

参照例（ExpressionLanguage）

step_meta('api_step', 'http_status')
step_meta('loop_step', 'total_iteration')

6. SOAP APIでの連携方法

SOAP APIはAPIリクエスト時にコンテンツをXML形式で送信する方式です。一方で、本システムのワークフローでは、全てのデータ整形・設定を一律でJSON形式で行う仕組みを採用しています。

詳細

SOAP APIを利用する場合、以下の流れでリクエストを組み立てます。

① ワークフローでの設定

ワークフローのmappingステップやtransformステップなどで、リクエストに必要なデータをJSON形式で定義します。
このJSONでは、以下の要素を使ってXML構造を表現します。

② API呼び出しステップでのXML形式への変換

API呼び出しステップ（ApiCallStep）で、上記JSON形式のデータをXMLに変換します。
システム内の変換機構は、@attributes・@valueなどのルールに基づき、自動的ににXMLを生成します。

注意事項

SOAP APIではAPI仕様によってXMLタグ順序を厳密に求められる場合があります。
しかし、MySQLのjson型カラムではデータ保存時にキー順序が保証されないため、取得時にタグの順序が変わる可能性があります。
@valueを用いることで、タグの順序を固定することが可能です。

設定例

最終的に以下のようなXMLをリクエストするSOAP APIでの通信を可能とするワークフローの設定方法を記載します。

<soap:Envelope xmlns:xsi="\&quot;http://www.w3.org/2001/XMLSchema-instance\" xmlns:xsd="\&quot;http://www.w3.org/2001/XMLSchema\" xmlns:soap="\&quot;http://schemas.xmlsoap.org/soap/envelope/\">
  <soap:Body>
    <RequestShipment xmlns="\&quot;https://wscsro.e-nekosolution.net/\">
      <pw>99999</pw>
      <id>BK001</id>
      <DataCount>2</DataCount>
      <Shipment_List>
        <Shipment_Data>
          <DataType>0</DataType>
          <UnsoIraiNo>20101222020002001</UnsoIraiNo>
        </Shipment_Data>
        <Shipment_Data>
          <DataType>0</DataType>
          <UnsoIraiNo>20101222020002002</UnsoIraiNo>
        </Shipment_Data>
      </Shipment_List>
    </RequestShipment>
  </soap:Body>
</soap:Envelope>

① モックデータの準備

モック的にマッピングステップでデータを準備します。実際はAPI呼び出しステップやファイル読み込みステップで変換元のデータを取得します。

ステップID：
data_mock

設定：

{
  "rules": {
    "shipment": [
      {
        "data_type": 0,
        "unso_irai_no": "'20101222020002001'"
      },
      {
        "data_type": 0,
        "unso_irai_no": "'20101222020002002'"
      }
    ]
  }
}

ステップのレスポンス：

{
  "shipment": [
    {
      "data_type": 0,
      "unso_irai_no": "20101222020002001"
    },
    {
      "data_type": 0,
      "unso_irai_no": "20101222020002002"
    }
  ]
}

② 繰り返し始点ステップ

小要素を生成するために繰り返しステップを使用して、以降のループの中で配列データを加工します。

ステップID: begin_loop

設定：

{
  "target": "step_data('data_mock', 'shipment', 0)"
}

ステップのレスポンス

{
  "data_type": 0,
  "unso_irai_no": "20101222020002001"
}

③ 変換ステップ

の中身、との整形を行います。
とのタグの順番を固定する必要がある場合は、@valueを用いて記載してください。
SOAP APIの仕様上、タグの順番を機にする必要がない場合は、@valueの使用は不要です。

ステップID: make_shipment_data

設定：

@valueなし
{
    "rules": [
        {
            "key": "DataType",
            "value": "step_data('begin_loop', 'data_type')"
        },
        {
            "key": "UnsoIraiNo",
            "value": "step_data('begin_loop', 'unso_irai_no')"
        }
    ]
}


@valueあり
{
  "rules": [
    {
      "key": "@value.0.DataType",
      "value": "step_data('begin_loop', 'data_type')"
    },
    {
      "key": "@value.1.UnsoIraiNo",
      "value": "step_data('begin_loop', 'unso_irai_no')"
    }
  ]
}

ステップのレスポンス

{
  "@value": [
    {
      "DataType": 0
    },
    {
      "UnsoIraiNo": "20101222020002001"
    }
  ]
}

④ 変換ステップ

前のステップで作成した変換を配列データに追加します。
はを複数兄弟要素として持つため、は配列になります。
ここではその「配列」を準備します。

ステップID: push_shipments

設定：

{
  "rules": [
    {
      "key": "shipments",
      "cases": [
        {
          "when": "loop_index == 0",
          "value": "array_push([], step_data('make_shipment_data'))"
        },
        {
          "when": true,
          "value": "array_push(step_data('push_shipments', 'shipments', loop_index - 1), step_data('make_shipment_data'))"
        }
      ]
    }
  ]
}

ステップのレスポンス

{
  "shipments": [
    {
      "@value": [
        {
          "DataType": 0
        },
        {
          "UnsoIraiNo": "20101222020002001"
        }
      ]
    }
  ]
}

⑤ 繰り返し終点

②〜④を繰り返して部分のデータの準備をします。

ステップID：
end_loop

設定：

{}

ステップのレスポンス：

{}

⑥ 変換ステップ

繰り返しステップの外で、繰り返し内で整形した配列データを取得し小要素に設定します。
、、、の兄弟要素を生成します。
、、、のタグの順番を固定する必要がある場合は、@valueを用いて記載してください。
SOAP APIの仕様上、タグの順番を機にする必要がない場合は、@valueの使用は不要です。

ステップID：make_request_shipment

設定：

@valueなし
{
    "rules": [
        {
            "key": "@attributes.xmlns",
            "value": "'https://wscsro.e-nekosolution.net/'"
        },
        {
            "key": "id",
            "value": "'BK001'"
        },
        {
            "key": "pw",
            "value": "'99999'"
        },
        {
            "key": "DataCount",
            "value": "step_meta('begin_loop', 'total_iteration')"
        },
        {
            "key": "Shipment_List.Shipment_Data",
            "value": "step_data('push_shipments','shipments', step_meta('begin_loop', 'total_iteration') - 1)"
        }
    ]
}

@valueあり
{
    "rules": [
        {
            "key": "@attributes.xmlns",
            "value": "'https://wscsro.e-nekosolution.net/'"
        },
        {
            "key": "@value.0.id",
            "value": "'BK001'"
        },
        {
            "key": "@value.1.pw",
            "value": "'99999'"
        },
        {
            "key": "@value.2.DataCount",
            "value": "step_meta('begin_loop', 'total_iteration')"
        },
        {
            "key": "@value.3.Shipment_List.Shipment_Data",
            "value": "step_data('push_shipments','shipments', step_meta('begin_loop', 'total_iteration') - 1)"
        }
    ]
}

ステップのレスポンス：

{
  "@attributes": {
    "xmlns": "https://wscsro.e-nekosolution.net/"
  },
  "@value": [
    {
      "id": "BK001"
    },
    {
      "pw": "99999"
    },
    {
      "DataCount": 2
    },
    {
      "Shipment_List": {
        "Shipment_Data": [
          {
            "@value": [
              {
                "DataType": 0
              },
              {
                "UnsoIraiNo": "20101222020002001"
              }
            ]
          },
          {
            "@value": [
              {
                "DataType": 0
              },
              {
                "UnsoIraiNo": "20101222020002002"
              }
            ]
          }
        ]
      }
    }
  ]
}

⑦ 変換ステップ

、、を生成します。

ステップID：
make_all

設定：

{
    "rules": [
        {
            "key": "soap:Envelope.@attributes.xmlns:xsi",
            "value": "'http://www.w3.org/2001/XMLSchema-instance'"
        },
        {
            "key": "soap:Envelope.@attributes.xmlns:xsd",
            "value": "'http://www.w3.org/2001/XMLSchema'"
        },
        {
            "key": "soap:Envelope.@attributes.xmlns:soap",
            "value": "'http://schemas.xmlsoap.org/soap/envelope/'"
        },
        {
            "key": "soap:Envelope.soap:Body.RequestShipment",
            "value": "step_data('make_request_shipment')"
        },
        {
            "key": "@xml_declaration.version",
            "value": "'1.0'"
        },
        {
            "key": "@xml_declaration.encoding",
            "value": "'utf-8'"
        }
    ]
}

ステップのレスポンス：

{
  "soap:Envelope": {
    "@attributes": {
      "xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance",
      "xmlns:xsd": "http://www.w3.org/2001/XMLSchema",
      "xmlns:soap": "http://schemas.xmlsoap.org/soap/envelope/"
    },
    "soap:Body": {
      "RequestShipment": {
        "@attributes": {
          "xmlns": "https://wscsro.e-nekosolution.net/"
        },
        "@value": [
          {
            "id": "BK001"
          },
          {
            "pw": "99999"
          },
          {
            "DataCount": 2
          },
          {
            "Shipment_List": {
              "Shipment_Data": [
                {
                  "@value": [
                    {
                      "DataType": 0
                    },
                    {
                      "UnsoIraiNo": "20101222020002001"
                    }
                  ]
                },
                {
                  "@value": [
                    {
                      "DataType": 0
                    },
                    {
                      "UnsoIraiNo": "20101222020002002"
                    }
                  ]
                }
              ]
            }
          }
        ]
      }
    }
  },
  "@xml_declaration": {
    "version": "1.0",
    "encoding": "utf-8"
  }
}

⑧ API呼び出し

API呼び出しステップにてSOPA形式でリクエストします。
request_typeにsoapを指定することで、自動的にJSONはXMLに変換されてリクエストされます。
response_typeにsoapを指定することで、レスポンスデータをSOAP APIに対応したXML形式で取得し、自動的にJSON形式に変換して保持します。

ステップID：
api_call

設定：

{
  "url": "'リクエスト先'",
  "body": "step_data('make_all')",
  "method": "'POST'",
  "headers": {
    "Content-Type": "'application/soap+xml; charset=utf-8'"
  },
  "request_type": "soap",
  "response_type": "soap"
}

リクエストで送信されるXML：

<?xml version=\"1.0\" encoding=\"utf-8\"?>
<soap:Envelope xmlns:xsi="\&quot;http://www.w3.org/2001/XMLSchema-instance\" xmlns:xsd="\&quot;http://www.w3.org/2001/XMLSchema\" xmlns:soap="\&quot;http://schemas.xmlsoap.org/soap/envelope/\">
  <soap:Body>
    <RequestShipment xmlns="\&quot;https://wscsro.e-nekosolution.net/\">
      <pw>99999</pw>
      <id>BK001</id>
      <DataCount>2</DataCount>
      <Shipment_List>
        <Shipment_Data>
          <DataType>0</DataType>
          <UnsoIraiNo>20101222020002001</UnsoIraiNo>
        </Shipment_Data>
        <Shipment_Data>
          <DataType>0</DataType>
          <UnsoIraiNo>20101222020002002</UnsoIraiNo>
        </Shipment_Data>
      </Shipment_List>
    </RequestShipment>
  </soap:Body>
</soap:Envelope>

ステップのレスポンス：

リクエスト先からのレスポンス