WordPress のフォームからケースを開始する（Case Starter Form）

WordPress に設置したフォームから、Questetra BPM Suite の ［メッセージ開始イベント (HTTP)］ を呼び出してケースを開始する方法を紹介します。本記事では、その動きを実際に確認できるリファレンス実装の WordPress プラグイン Case Starter Form を使って、導入手順と内部の仕組みを解説します。

このプラグインは preset レジストリ方式 を採用しており、1 つのインストールのまま、複数の開始イベント（フォーム）を別々のページで出し分けられます。

curl 編・Python 編 と同じく「Questetra BPM Suite の外からケースを開始する」シリーズの一編として、外部の Web フォームから業務を起動するパターンを扱います。

これはリファレンス実装です（公式プラグインではありません） 本記事で紹介するプラグインは「動かし方」を示すためのサンプルです。公式プラグインとしての提供・サポートは行っておらず、MIT ライセンスの無保証ソフトウェアです。内容を理解のうえ、自己責任でご利用ください。 リポジトリ: https://github.com/Questetra/wordpress-case-starter-form

どんなときに使うか（［メッセージ開始イベント (フォーム)］ との使い分け）

外部から Web フォームでケースを開始したいだけであれば、まず Questetra 標準の ［メッセージ開始イベント (フォーム)］ を検討してください。多くの業務シーンでは、これで十分 です。フォームを Questetra 内で設計・管理でき、データ項目との対応・入力チェック・多言語対応なども標準機能でまかなえ、保守も簡単です（本シリーズ 中級者編「公開フォームを作成する」を参照）。

本記事のように、WordPress 側でフォームを作って HTTP でケースを起動する構成が向くのは、サイトのデザインやブランディングに溶け込ませる必要がある、マーケティング目的のフォーム など、デザイン性が強く求められる限られた場面です。

さらに、不特定多数の一般コンシューマ向けに本格運用する場合は、スパム対策・運用負荷の観点から、専用のフォーム作成サービスと組み合わせる 方が適しています。

応答速度の面でも一点。本構成は、WordPress が Questetra への送信を 同期的に待ってから 完了画面を返すため、応答時間が Questetra への往復に左右されます（送信から完了表示までに待ちが生じやすい）。一方、多くのホスト型フォームサービスは、回答者にはその場で完了を返し、外部連携（Webhook など）はバックグラウンドで行うため、回答者の体感速度の面で有利です（この場合、Questetra でのケース起動は事後になります）。

全体像

［WordPress］
 入力フォーム（ページに preset 名だけを埋め込み）
   │ 送信（ブラウザ → 自サイト内）
   ▼
 プラグイン（サーバサイド）
   │ preset 名から endpoint・key を引く（レジストリはサーバ側）
   │ URL・API キーはサーバ側のみで保持
   │ multipart/form-data で POST
   ▼

［Questetra BPM Suite］
 メッセージ開始イベント (HTTP)
   │
   ▼
 ケース開始

ポイントは、ブラウザから Questetra へ直接送るのではなく、いったん WordPress（サーバ側）が受けて、そこから Questetra へ送る ことです。これにより、起動 URL と API キーをブラウザ（ページのソース）に一切出さずに済み、ブラウザの CORS 制約も受けません。

設計上の不変条件

このプラグインは、次の不変条件を守る設計になっています。

秘密と接続先（endpoint / key）は preset レジストリ＝サーバ側に残し、コンテンツ層（ショートコード属性）に渡るのは preset 名だけ。

• endpoint（起動 URL）と key（API キー）は ショートコード属性で指定できません。
• ブラウザ（ページの本文）に出るのは preset 名だけ で、サーバ側がレジストリから実値を引きます。

これにより、記事・固定ページの編集者（コンテンツ層）に秘密を触らせずに、フォームだけを各ページへ配置できます。

前提（準備）

Questetra 側

• ［メッセージ開始イベント (HTTP)］ を含むワークフローアプリ（メッセージ開始イベント (HTTP) が利用できるエディション）
• そのイベントの 起動 URL と API キー（アプリ設定画面で確認できます）
• 受け取りたい 受信パラメータ（データ項目） の名前と型

受信パラメータの確認方法は、本シリーズの「準備編」を参照してください。

WordPress 側

• 独自プラグインを設置できる WordPress 環境 が必要です。
  • WordPress.com の無料プランでは独自プラグインを設置できません（全有料プランで利用可能）。
  • 手元で試すだけであれば、リポジトリ同梱の Docker 環境（example-docker/）や、ローカル WordPress（Studio / Local など）が手軽です。

導入手順

1. プラグインを入手する

リポジトリ（https://github.com/Questetra/wordpress-case-starter-form）から questetra-case-starter-form/ フォルダを取得します。

2. preset を設定する

questetra-case-starter-form/questetra-case-starter-form.php の冒頭にある QSCF_PRESETS 定義ブロックだけ を編集します。ファイル内の ■■■ これより下はロジック本体 ■■■ より下は編集不要です（どこまでが設定かはコメントで示してあります）。フォームを増やしたいときは preset を増やすだけです。

define( 'QSCF_PRESETS', array(
    // preset 名 'contact'（問い合わせフォーム）
    'contact' => array(
        'endpoint'       => 'https://your-tenant.questetra.net/System/Event/MessageStart/0000/00/start',
        'key'            => 'PUT-YOUR-API-KEY-HERE',  // ← 自分の API キーに置き換え
        'fields'         => array(
            array( 'param' => 'title',     'label' => '件名',           'type' => 'text',     'required' => false ),
            array( 'param' => 'q_string0', 'label' => 'お名前',         'type' => 'text',     'required' => true ),
            array( 'param' => 'q_string1', 'label' => 'お問い合わせ内容', 'type' => 'textarea', 'required' => true ),
            array( 'param' => 'q_file11',  'label' => '添付ファイル',     'type' => 'file',     'required' => true ),
        ),
        'thanks'         => 'お問い合わせありがとうございました。',  // 任意。省略時はデフォルト文言
        'max_file_bytes' => 10 * 1024 * 1024,                        // 任意。省略時は 10MB
    ),
    // 2つ目以降は preset をコピーして名前と内容を変えるだけ
    // 'apply' => array( ... ),
) );

API キーについて

key には、対象の開始イベントの API キーを直接記述します（PUT-YOUR-API-KEY-HERE を自分のキーに置き換え）。送信はサーバサイドで行うため、キーがページソースに出ることはありません。プラグインをバージョン管理する場合も private リポジトリでの管理を想定 しているため、直書きで問題ありません。

（おまけ）wp-config.php を編集できる環境では、そこにキーを定義し 'key' => defined( 'QSCF_CONTACT_KEY' ) ? QSCF_CONTACT_KEY : '', のように参照して、プラグイン本体からキーを分離することもできます（public リポジトリで管理する場合など）。ただし WordPress.com では通常 wp-config.php を編集できない ため、その場合は上記の直書きを使ってください。

fields の各キー

ファイルは常に複数添付できます。「○個以上」などの個数チェックは Questetra 側のデータ項目設定で行われ、エラーはそのまま該当フィールドに表示されます（プラグインは個数のルールを持ちません）。

3. ZIP 化してアップロードし、有効化する

設定を済ませた questetra-case-starter-form/ フォルダを ZIP 形式にまとめます（フォルダ直下に questetra-case-starter-form.php がある状態）。WordPress の管理画面で ［プラグイン］→［新規追加］→［プラグインのアップロード］ を開き、その ZIP をアップロードして「Questetra Case Starter Form (Reference)」を有効化します。

WordPress.com（Business 以上）では、ZIP アップロードのほかに SFTP や GitHub 連携でのファイル配置も可能ですが、まずは ZIP アップロードが簡単です。アップロード後はプラグインのソースを編集できない場合があるため、設定（手順 2）を済ませてから ZIP 化 してください。

4. 固定ページにフォームを埋め込む

任意の固定ページ・投稿の本文に、preset 名を指定したショートコードを記述します。

[qscf_form preset="contact"]

• preset … 使用する preset 名（必須。未指定時は "default" を探し、なければ管理者にだけ注意を表示）
• thanks … 送信成功メッセージの上書き（任意）。例: [qscf_form preset="contact" thanks="受け付けました"]
  • endpoint・key・fields はショートコード属性からは指定できません（前述の不変条件）。

別のフォームを別ページに置きたいときは、preset を追加して [qscf_form preset="別名"] を貼るだけです。

動作確認

公開したページを開き、フォームに入力して送信します。

• 入力に問題がなければ、Questetra でケースが開始され、ページには サンクスメッセージ と 送信内容（起動したケース ID を含む） が表示されます。
• Questetra 側のアプリ設定画面、対象イベントの「自動処理ログ」にも、ケース開始の記録が残ります。

入力に不備がある場合は、該当する入力欄の下にエラーメッセージ が表示され、入力済みの値は保持されます（ファイル欄はブラウザの仕様上、選び直しになります）。Questetra 側のバリデーション（例:「添付ファイルは 2 以上にしてください」）も、対応する項目の下に表示されます。

仕組みの解説

リファレンス実装として、押さえておきたい設計上のポイントを紹介します。

preset 名だけをコンテンツ層に渡す

フォームには preset 名だけを hidden フィールドで埋め込みます。送信を受けたサーバ側ハンドラは、その preset 名を ホワイトリスト検証（QSCF_PRESETS に存在するか）し、登録済みなら endpoint・key・fields をレジストリから取得します。endpoint や key をブラウザから受け取ることはありません。

サーバサイドで中継する（URL・キーの秘匿、CORS 不要）

フォームの送信先は Questetra ではなく、WordPress の admin-post.php（サーバ側の処理）です。サーバ側で起動 URL に API キーを付与し、wp_remote_post() で Questetra へ送ります。これにより、起動 URL と API キーがブラウザに渡らず、ブラウザの CORS 制約も受けません。

multipart/form-data でファイルも送る

文字項目は通常のフォーム値として、ファイル項目は multipart/form-data のファイルパートとして、受信パラメータ名（param）で送信します。ファイルが複数ある場合は同じパラメータ名で繰り返し送ります。

Post / Redirect / Get（二重起票の防止）

送信（POST）を受けたら、結果を一時データ（transient）にいったん保存し、合言葉（ランダムなトークン）だけを付けて 元のページへリダイレクト します。戻ってきたページ（GET）でその合言葉を使ってデータを取り出し、サンクス画面を描画します。

この方式により、

• 完了画面でのリロードによる 再送信（二重起票）を防げる
• 送信内容を URL に載せずに 受け渡せる（情報の露出・URL 汚染を回避）

といった利点があります。一時データは preset 名にも紐づけて保存するため、同一ページに複数のフォームを置いても取り違えません。

項目ごとのバリデーション

プラグイン側の必須チェックに加え、Questetra が返すエラー（XML の <key>／<detail>）を解析し、受信パラメータ名が一致する項目の下にメッセージを振り分けて 表示します。どの項目にも紐づかないエラー（通信失敗など）は、フォーム上部にまとめて表示します。なお CSRF トークン切れの場合は、エラーページで「戻る」案内を表示します。

複数フォームに対応する

このプラグインは preset レジストリ方式なので、QSCF_PRESETS に preset を追加するだけ で複数のフォームに対応できます。

• 接続先や項目が異なるフォームを増やす → preset を 1 つ追加（endpoint / key / fields を設定）
• それぞれのページに [qscf_form preset="preset名"] を貼る

1 インストールのまま、問い合わせ用・申請用など複数の開始イベントを別々のページで運用できます。

注意点・制限

• 公開フォームのスパム対策: 誰でもアクセスできるページに設置する場合は、reCAPTCHA などの対策を別途検討してください。
• 入力フィールドの種類: 用意しているフィールドは text（1 行）/ textarea（複数行）/ file の 3 種類です。HTTP の受信パラメータには値が文字列で渡るため、QBPMS の数値型・日付型などのデータ項目でも、テキスト入力で値を送れば設定できます（妥当性は Questetra 側で検証されます）。一方、選択肢のプルダウンや日付ピッカーといった専用の入力 UI は用意していません（必要なら同じ枠組みで追加できます）。
• 項目ごとの制約は Questetra 側で検証: 文字数の上限や、ファイルの必要数といった項目ごとのルールは、プラグインではなく Questetra のデータ項目設定で検証され、エラーは該当フィールドの下に表示されます。

まとめ

WordPress のフォームから ［メッセージ開始イベント (HTTP)］ を呼び出せば、お問い合わせや申請などの Web 受付を、そのまま Questetra のケースとして起動できます。本記事のリファレンス実装 Case Starter Form は、preset レジストリ方式による複数フォーム対応・サーバサイド中継・ファイル送信・完了画面・項目別エラー表示といった実装のポイントを、まとめて確認できる教材として活用いただけます。

• リポジトリ: https://github.com/Questetra/wordpress-case-starter-form

本記事のプラグインはリファレンス実装（非公式・MIT・無保証・サポート対象外）です。