開発情報・ナレッジ

投稿者: SPIRERS ナレッジ向上チーム 2022年9月30日 (金)

フォームの送信完了後にAPIでメール配信をするサンプルプログラム

SPIRAL ver.2のフォームのメールアクションでは、登録や更新があったレコードのメールアドレスにメールを送信することはできますが、複数のレコードや他DBのレコード宛てにメールを送信することはできません。
フォームの送信完了後に、条件に当てはまる複数のレコード当てや、他DBのレコード宛てにメールを送信することができるサンプルプログラムを紹介します。

このサンプルプログラムを使うことで実装できるメール配信例

このサンプルコードを使うことで、フォーム送信完了後に一斉条件配信や他DBへの配信を行なうことができます。
(例1)企業会員が追加されたら、同じ企業に所属する他の会員にも登録通知メールを送る
(例2)企業情報が更新されたら、その企業に所属する会員宛てに変更通知メールを送る
下記のように、更新したレコードのフィールド内のメールアドレスにメールを送る場合は、フォームのメールアクションで設定ができるためこのサンプルプログラムは必要ありません。

サンプルプログラム

PHP
<?php
//------------------------------
// 設定値
//------------------------------
define("API_URL", "https://api.spiral-platform.com/v1");
define("API_KEY", $SPIRAL->getEnvValue(""));
define("API_ROLE",$SPIRAL->getEnvValue("")); // ロールによるAPI権限が不要の場合
define("APP_ID",$SPIRAL->getEnvValue(""));
define("DB_ID",$SPIRAL->getEnvValue(""));

//------------------------------
// API実行
//------------------------------
$commonBase = CommonBase::getInstance();

$formComplete = $SPIRAL->getRegistrationForm("ブロックの識別名"); // 登録フォームブロックの識別名を登録
// $formComplete = $SPIRAL->getUpdateForm("ブロックの識別名"); // 更新フォームブロックの識別名を登録
// $formComplete = $SPIRAL->getDeleteForm("ブロックの識別名"); // 削除フォームブロックの識別名を登録

$record = $SPIRAL->getRecordValue();

if ($formComplete->isCompletedStep()) {
    $body = array(
        "to" => array(
            "field" => "X", // 宛先メールアドレスのフィールドID
            "where" => array( // 条件抽出
                "type" => "simple",
                "value" => array(
                    "operator" => "and",
                    "conditions" => [
                        array(
                            "field" => "@newField",
                            "operator" => "eq",
                            "value1" => "XXXX"
                        )
                    ]
                )
            )
        ),
        "excludeErrorCount" => 1, // 配信エラー除外の対象とするエラーの発生回数
        "from" => array(
            "displayName" => "ナレッジサイト事務局", // 差出人表示名
            "emailLocalPart" => "info", // 差出人メールアドレスのローカルパート
            "emailFromDomainId" => XXX // メール差出人ドメインID
        ),
        "subject" => array(
            "content" => "メール件名" // メール件名
        ),
        "plainBody" => array(
            "content" => "メールの本文" // メール本文
        ),
        "timing" => "now",
        "status" => "ready"
    );

    $express = $commonBase->apiCurlAction("POST", "/apps/" . APP_ID . "/dbs/" . DB_ID . "/express/email", $body);

    // レスポンスを Thymeleaf に受け渡す
    $SPIRAL->setTHValue("API_RESPONSE", $express);
}

//------------------------------
// 共通モジュール
//------------------------------
class CommonBase {
    /**
     * シングルトンインスタンス
     * @var UserManager
     */
    protected static $singleton;

    public function __construct() {
        if (self::$singleton) {
            throw new Exception('must be singleton');
        }
        self::$singleton = $this;
    }
    /**
     * シングルトンインスタンスを返す
     * @return UserManager
     */
    public static function getInstance() {
        if (!self::$singleton) {
            return new CommonBase();
        } else {
            return self::$singleton;
        }
    }
    /**
     * V2用 API送信ロジック
     * @return Result
     */
    function apiCurlAction($method, $addUrlPass, $data = null) {
        $header = array(
            "Authorization:Bearer ". API_KEY,
            "Content-Type:application/json",
            "X-Spiral-Api-Version: 1.1",
        );
        if(API_ROLE){
			$header = array_merge($header,array("X-Spiral-App-Role: ".API_ROLE));
		}
        // curl
        $curl = curl_init();
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($curl, CURLOPT_URL, API_URL. $addUrlPass);
        curl_setopt($curl, CURLOPT_HTTPHEADER, $header);
        if ($method == "POST") {
            curl_setopt($curl, CURLOPT_POSTFIELDS , json_encode($data));
            curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method);
        }
        $response = curl_exec($curl);
        if (curl_errno($curl)) echo curl_error($curl);
        curl_close($curl);
        return json_decode($response , true);
    }
}

利用方法

サンプルプログラムは、フォームブロックを設置するページのPHPタブにセットしてください。
各設定値をセットしたPHP環境変数を設定する
define("API_KEY", $SPIRAL->getEnvValue(""));
define("API_ROLE",$SPIRAL->getEnvValue("")); // ロールによるAPI権限が不要の場合
define("APP_ID",$SPIRAL->getEnvValue(""));
define("DB_ID",$SPIRAL->getEnvValue(""));
API_KEY
6行目
アカウント管理で発行したAPIキーをセットしたPHP環境変数の変数名
API_ROLE
7行目
アプリロールの識別名をセットしたPHP環境変数の変数名
アプリロールによる権限設定をしない場合は未入力
APP_ID
8行目
更新するアプリのIDをセットしたPHP環境変数の変数名
DB_ID
9行目
更新するDBのIDをセットしたPHP環境変数の変数名
API_KEY, API_ROLE, APP_ID, DB_ID など複数ページで使用する値は、PHP環境変数への設定を推奨しております。
PHP環境変数の設定方法は、サポートサイト PHP環境変数をご確認ください。

環境変数を使用しない場合は、getEnvValue()を使用せずに下記のように直接記載してください。
define("API_KEY", "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx");
define("API_ROLE", "XXXAppRole"); // アプリロールを使用しない場合は未入力
define("APP_ID", "XXXXX");
define("DB_ID", "XXXXX");
フォームブロックの識別名を設定する
フォームの送信が完了したかを判定するため、フォームブロックの識別名を設定します。
使用しないブロックタイプの設定は、コメントアウト(*)してください。
* 文字の先頭に「//」をつけることでコメントアウトできます。
$formComplete = $SPIRAL->getRegistrationForm("ブロックの識別名"); // 登録フォームブロックの識別名を登録
// $formComplete = $SPIRAL->getUpdateForm("ブロックの識別名"); // 更新フォームブロックの識別名を登録
// $formComplete = $SPIRAL->getDeleteForm("ブロックの識別名"); // 削除フォームブロックの識別名を登録
リクエストボディのパラメータを設定する
リクエストボディで使用する主要なパラメータについて解説いたします。
その他のパラメータや詳細使用については、APIリファレンス レコード一覧を取得をご確認ください。
to(宛先設定)
        "to" => array(
            "field" => "X", // 宛先メールアドレスのフィールドID
            "where" => array( // 条件抽出
                "type" => "simple",
                "value" => array(
                    "operator" => "and",
                    "conditions" => [
                        array(
                            "field" => "@newField",
                            "operator" => "eq",
                            "value1" => "XXXX"
                        )
                    ]
                )
            )
        ),
field
25行目
宛先メールアドレスのフィールドID
where
26行目
条件抽出を記載
条件抽出の設定例を下記に記載しています。
・条件抽出(where)の設定例
例1.フォームで送信した値を条件に使用する
フォームで更新したレコードの企業ID(テキスト)と、メールを配信する会員DBの所属企業ID(テキスト)が一致するデータに配信する例です。
"where" => array( // 条件抽出
    "type" => "simple",
    "value" => array(
        "operator" => "and",
        "conditions" => [
            array(
                "field" => "@companyID",
                "operator" => "eq",
                "value1" => $record['item']['companyID']
            )
        ]
    )
)
例2.複数の条件を指定する
フォームで更新したレコードの企業ID(テキスト)とメールを配信する会員DBの所属企業ID(テキスト)が一致する かつ、 管理者フラグ(セレクト)が「1:管理者」のデータに配信する例です。
"where" => array( // 条件抽出
    "type" => "simple",
    "value" => array(
        "operator" => "and",
        "conditions" => [
            array(
                "field" => "@companyID",
                "operator" => "eq",
                "value1" => $record['item']['companyID']
            ),
            array(
                "field" => "@adminFlg",
                "operator" => "eq",
                "value1" => "1"
            )
        ]
    )
)
from(差出人設定)
        "from" => array(
            "displayName" => "ナレッジサイト事務局", // 差出人表示名
            "emailLocalPart" => "info", // 差出人メールアドレスのローカルパート
            "emailFromDomainId" => XXX // メール差出人ドメインID
        ),
displayName
42行目
差出人表示名
emailLocalPart
43行目
差出人メールアドレスのローカルパート
emailFromDomainId
44行目
メール差出人ドメインID
IDは「アカウント管理」>「メール差出人ドメイン」から、ドメイン名をクリックした画面で確認できます。
subject(件名)
        "subject" => array(
            "content" => "メール件名" // メール件名
        ),
content
47行目
件名の内容
最大128byte
plainBody(テキストメールの本文)
        "plainBody" => array(
            "content" => "メールの本文" // メール本文
        ),
content
50行目
本文の内容
最大1MiB
メール文面に差し替えキーワード、フォームで送信されたデータ、改行を入れる場合の記述方法
差し替えキーワード 配信対象者の情報をメール文面に入れる場合は差し替えキーワードを使用し、
{{@DB識別名.フィールド識別名}}」と記載します。
差替えキーワードのフォーマットはサポートサイトをご確認ください。
フォームで送信されたデータ フォームで送信されたデータをメール文面に入れる場合は、
$record['item']['フィールド識別名']」と記載します。
PHPの変数のため、
"登録されたデータは".$record['item']['フィールドの識別名']."です。"」というように結合して記載する必要があります。
改行 改行は「\n」で記載します。
記述例
"content" => "{{@memberDB.name}}\n\n以下の企業会員が追加されました。\n\n【氏名】".$record['item']['name']."\n【メールアドレス】".$record['item']['email']
差し替えられた後のメール文面
ナレッジ 花子様

以下の企業会員が追加されました。

【氏名】ナレッジ 太郎
【メールアドレス】knowledge.taro@spiral-platform.co.jp
timing(配信タイミング)
        "timing" => "now",
配信タイミングを scheduled(予約配信) か now(即時配信)で選択します。
サンプルプログラムでは即時配信するため、nowを指定しています。
scheduleDate(予約日時)のパラメータも用意したうえでscheduledを指定することで、日時指定での配信も可能です。
status(ステータス)
        "status" => "ready"
ステータスを setting(設定中)かready(設定完了)で選択します。
サンプルプログラムでは即時配信するため、readyを指定しています。
settingを指定するとメールは配信されないため、APIでのメール配信設定が正しく行われるかをテストすることができます。

APIで実行された配信設定の確認方法

サンプルプログラムのように配信タイミングが「now」かつ、ステータスが「ready」で作成された配信設定は、配信対象DBのアプリ利用画面から「メール配信」タブ >「配信済」をクリックすることで確認ができます。

解決しない場合はこちら コンテンツに関しての
要望はこちら