アクションの通知設定

アクションの通知設定

アクションごとに、実行成功時やエラー時の通知を設定できます。

前提条件

アクションの通知設定を行なうには、以下の準備が完了している必要があります。


(旧)JavaScriptアクションでは通知設定は利用できません。通知機能を利用するには、JavaScriptアクションへの移行をご検討ください。

必要なロール

アクションの通知設定を行なうには、以下のいずれかのロールが設定されたグループに所属している必要があります。

  • プロジェクト管理者
  • 開発責任者
  • 開発者

ロールの詳細はグループをご覧ください。

通知設定の方法

  1. アクションの編集画面を開きます。
  2. 「通知設定」のステップに進みます。
  3. 「成功時の通知」または「エラー時の通知」を設定します。
アクション編集画面の通知設定ステップ

成功時の通知

「成功時の通知を有効にする」をONにすると、アクションの実行が成功したときに通知を送信します。

エラー時の通知

「エラー時の通知を有効にする」をONにすると、アクションの実行中にエラーが発生した場合に通知を送信します。

HTTP APIアクションでHTTPステータスコードによるエラー判定を行なうには、「200系以外のレスポンスステータスコードを実行エラーとして扱う」を有効にしてください。

設定項目

各通知設定では、以下の項目を設定できます。

通知方法

通知方法の管理で作成した通知方法を選択します。選択した通知方法の環境ごとの通知先チャンネルが表示されます。

メンション先ユーザー

通知メッセージでメンションするユーザーを選択します。複数のユーザーを選択できます。

ベースマキナと同じメールアドレスのSlackユーザーが存在するプロジェクトユーザーから選択できます。メンションはメッセージの先頭に表示されます。

メッセージのカスタマイズ

「成功時のメッセージをカスタマイズする」または「エラー時のメッセージをカスタマイズする」をONにすると、通知メッセージをカスタマイズできます。

メッセージはSlackの書式(mrkdwn形式) (opens in a new tab)で記述できます。また、事前定義パラメーターとアクションのパラメーターを使用して動的な値を埋め込めます。

通知メッセージでのみ使用できる値は以下のとおりです。

  • {{ action.results }} - 全実行結果の配列
  • {{ action.success }} - 1つ目の実行結果(action.results[0].successと同等、成功時のみ)
  • {{ action.failure }} - 1つ目の失敗内容(action.results[0].failureと同等、エラー時のみ)
  • {{ action.metadata }} - 1つ目の実行結果のメタデータ(action.results[0].metadataと同等)

MySQLなどのSQLアクションでは複数のクエリを登録でき、それぞれのクエリに対応する実行結果が返ってきます。2つ目以降の実行結果を使用する場合はaction.results[1].successのようにアクセスしてください。

これらのパラメーターではプロパティアクセスとインデックスアクセスが使用できます。

  • プロパティアクセス:{{ action.success.someKey }}
  • インデックスアクセス:{{ action.success.data[0] }}

存在しないパラメーターを指定した場合、エラーメッセージが表示されます。

パラメーターの値の表示形式

パラメーターの値は、入力値の種類に応じて以下のように表示されます。

入力値の種類表示形式
テキスト値がそのまま表示されます。空の場合は (未入力) と表示されます。選択肢が設定されている場合は、選択肢のラベルが表示されます。
数値値が数値として表示されます。未入力の場合は (未入力) と表示されます。選択肢が設定されている場合は、選択肢のラベルが表示されます。
SQLテキストと同様に表示されます。
(非推奨)システム値テキストと同様に表示されます。
真偽値フォーマット形式が「文字列」の場合は設定した「真の場合の値」または「偽の場合の値」が表示されます。「フォーマットなし」の場合は true または false が表示されます。
日付設定した日付の形式で表示されます。「unixtimeとして利用する」が有効な場合は数値として表示されます。未入力の場合は (未入力) と表示されます。
ファイルファイルパラメーターの値は表示できません と表示されます。
JSON値nullの場合は null と表示されます。それ以外は、設定した「JSON値の種類」(テキスト、数値、日付)に応じて表示されます。
配列各要素が「要素の種類」に応じて変換され、カンマ区切りで表示されます。空配列の場合は (未入力) と表示されます。
タプル各要素が「要素の種類」に応じて変換され、カンマ区切りで表示されます。

実行結果の値の表示形式

実行結果へのアクセス({{ action.success }}{{ action.success.key }}{{ action.success[0] }} など)では、値の型に応じて以下のように表示されます。

値の型表示形式
文字列値がそのまま表示されます。
数値数値が文字列に変換されて表示されます。NaNInfinityもそのまま表示されます。
真偽値true または false が表示されます。
オブジェクトJSON文字列に変換されて表示されます(例: {"key":"value"})。循環参照など文字列化できない場合はエラーメッセージが表示されます。
配列JSON文字列に変換されて表示されます(例: [1,2,3])。
nullnull と表示されます。
ファイル(Blob)「〜の値はファイルのため通知で表示できません」というエラーメッセージが表示されます。

通知メッセージの設定例

以下に、通知メッセージのカスタマイズ例を紹介します。

基本的な設定例

実行者と環境を含む通知

{{ currentUser.name }} が {{ action.name }} を実行しました。
環境: {{ environment.name }}

パラメーターを含む通知

アクションにuserNamenewStatusというパラメーターがある場合の例です。

ユーザー「{{ userName }}」のステータスを「{{ newStatus }}」に更新しました。
実行者: {{ currentUser.name }}

実行結果を使った設定例

HTTP APIの結果を表示

HTTP APIアクションで {"user": {"id": 123, "name": "田中太郎"}} のようなレスポンスが返る場合の例です。

ユーザー情報を取得しました。
- ID: {{ action.success.user.id }}
- 名前: {{ action.success.user.name }}

配列データの表示

HTTP APIアクションで {"items": [{"name": "商品A"}, {"name": "商品B"}]} のようなレスポンスが返る場合の例です。

最初の商品: {{ action.success.items[0].name }}

エラー時の通知例

エラー時の通知では {{ action.failure }} を使用してエラー内容を表示できます。

基本的なエラー通知

アクション「{{ action.name }}」の実行に失敗しました。
エラー内容: {{ action.failure }}
実行者: {{ currentUser.name }}
環境: {{ environment.name }}

エラー詳細へのネストアクセス

エラーが {"message": "ユーザーが見つかりません", "code": "USER_NOT_FOUND"} のような構造の場合、プロパティにアクセスできます。

エラーが発生しました。
メッセージ: {{ action.failure.message }}
エラーコード: {{ action.failure.code }}

JavaScriptアクションとの組み合わせ

より高度な通知をする場合、JavaScriptアクションでデータを加工し、その結果を通知メッセージで使用できます。

データの集計

売上データを集計して通知する例です。

JavaScriptアクションのコード:

import { executeAction } from "@basemachina/action";
 
/** @type { import("@basemachina/action").Handler } */
export default async () => {
  // 売上データを取得するアクションを実行
  const result = await executeAction("get-sales-data");
  const sales = result[0].success;
 
  const total = sales.reduce((sum, s) => sum + s.amount, 0);
  const count = sales.length;
 
  return {
    summary: `${count}件の売上、合計${total.toLocaleString()}円`,
    topSale: sales.sort((a, b) => b.amount - a.amount)[0],
  };
};

通知メッセージ:

本日の売上レポート
{{ action.success.summary }}
最高額: {{ action.success.topSale.amount }}円({{ action.success.topSale.customerName }}様)

条件に応じたメッセージ

在庫数に応じて表示内容を変える例です。

JavaScriptアクションのコード:

import { executeAction } from "@basemachina/action";
 
/** @type { import("@basemachina/action").Handler } */
export default async ({ productId }) => {
  // 在庫数を取得するアクションを実行
  const result = await executeAction("get-stock-count", { productId });
  const stock = result[0].success.count;
 
  let status;
  if (stock === 0) {
    status = "在庫切れ";
  } else if (stock < 10) {
    status = "在庫僅少";
  } else {
    status = "在庫あり";
  }
 
  return { productId, stock, status };
};

通知メッセージ:

商品ID: {{ action.success.productId }}
ステータス: {{ action.success.status }}
現在の在庫数: {{ action.success.stock }}

複数データソースの統合

ユーザー情報と注文情報を1つの通知にまとめる例です。

JavaScriptアクションのコード:

import { executeAction } from "@basemachina/action";
 
/** @type { import("@basemachina/action").Handler } */
export default async ({ userId }) => {
  // ユーザー情報を取得
  const userResult = await executeAction("get-user", { userId });
  const user = userResult[0].success;
 
  // 注文情報を取得
  const ordersResult = await executeAction("get-orders", { userId });
  const orders = ordersResult[0].success;
 
  const totalSpent = orders.reduce((sum, o) => sum + o.total, 0);
 
  return {
    userName: user.name,
    email: user.email,
    orderCount: orders.length,
    totalSpent: totalSpent.toLocaleString(),
  };
};

通知メッセージ:

顧客情報サマリー
- 名前: {{ action.success.userName }}
- メール: {{ action.success.email }}
- 注文回数: {{ action.success.orderCount }}回
- 累計購入額: {{ action.success.totalSpent }}円

エラーハンドリングと通知

複数のアクションを実行するワークフローで、どのステップで失敗したかを通知する例です。ResultErrorを使って構造化されたエラー情報を返します。

JavaScriptアクションのコード:

import { executeAction, ResultError } from "@basemachina/action";
 
/** @type { import("@basemachina/action").Handler } */
export default async ({ userId, imageFile }) => {
  // ステップ1: 画像をアップロード
  const uploadResult = await executeAction("upload-image", { imageFile });
  if (uploadResult[0].failure) {
    throw new ResultError({
      step: "画像アップロード",
      message: "画像のアップロードに失敗しました",
      detail: uploadResult[0].failure,
    });
  }
 
  // ステップ2: ユーザー情報を更新
  const imagePath = uploadResult[0].success.path;
  const updateResult = await executeAction("update-user-image", {
    userId,
    imagePath,
  });
  if (updateResult[0].failure) {
    throw new ResultError({
      step: "ユーザー情報更新",
      message: "ユーザー情報の更新に失敗しました",
      detail: updateResult[0].failure,
    });
  }
 
  return { userId, imagePath };
};

エラー時の通知メッセージ:

ワークフローでエラーが発生しました。
失敗したステップ: {{ action.failure.step }}
エラー内容: {{ action.failure.message }}
詳細: {{ action.failure.detail }}

通知の送信が失敗した場合

Slackへの通知送信が失敗した場合、アクションを実行したユーザーへメールで通知が送信されます。