rex0220 kSQL アクションプラグイン - 事例: デモデータを初期化する

「rex0220 kSQL アクションプラグイン」の事例です。やりたいことから探せる事例集の 1 件です。

この記事は、ひとつの業務を、画面・設定・SQL・AI への頼み方まで通して見せます。設定の要点・SQL の全文・AI への頼み方は畳んであります（開くと読めます）。機能ごとの説明は、末尾の「関連記事」にある概要と ①〜⑫ の記事にまとめてあります。

やりたいこと

デモや研修で触って散らかったデータを、ボタン 1 つで最初の状態に戻したい。

戻すデータの日付は、押した日を基準に作り直します。決まった日付で入れておくと、時間が経つうちに「今月」「直近 1 週間」の絞り込みから外れてしまうためです。

画面と結果

一覧の上のパネルにある［デモデータ初期化］を押すと、確かめのダイアログが出ます。［はい］を選んで［実行］を押します。

受注アプリと受注明細アプリの全レコードを消して、受注 5 件・明細 11 件を入れ直します。最後に、明細の小計を受注番号ごとに足して、受注の合計金額に書き込みます。

完了のダイアログの［画面を更新］を押すと、一覧が読み直されます（自動では読み直しません）。

11 月 8 日に押したときの受注は、次のとおりです。

受注番号	受注日	納期	ステータス	合計金額	日付の決め方
DEMO-001	11-08	11-15	受付	7,400 円	押した日 / その 7 日後
DEMO-002	11-05	11-12	手配中	201,000 円	押した日の 3 日前 / 押した日の 4 日後
DEMO-003	11-01	11-11	出荷済	241,800 円	押した日の 15 日前 / 受注日の 10 日後
DEMO-004	11-01	11-15	完了	49,000 円	月初 / 月初の 14 日後
DEMO-005	10-08	10-15	完了	7,000 円	先月の同じ日 / その 7 日後

• DEMO-001〜004 が今月分（ステータスが混ざる）、DEMO-005 が先月分（比べるため）です。
• 「押した日の 3 日前・15 日前」が先月に入るときは、月初にそろえます。DEMO-003 は 10 月 24 日になるところを 11 月 1 日にしています。こうしておくと、月の初めに押しても今月分は 4 件のままです。
• 先月に同じ日が無いとき（3 月 31 日に押したときなど）は、先月の末日になります。

自分のアプリで使うとき

SQL の中では、アプリを番号ではなく名前で書いています（LAPP_受注 のような名前。設定の「論理アプリ」で、名前とアプリ番号を結び付けます）。そのため、アプリ番号はふつう論理アプリの表を直せば差し替えられます。この事例では、アプリ番号をパラメーター expect_app にも書いているので、そちらも直します（下の「変えるところ」）。

ただし、項目は合わせる必要があります。下の「使うアプリと項目」の表にある項目コード・種類・「値の重複を禁止する」の設定が違うと、そのままでは動きません。違うところは、表の下の「変えるところ」を見て SQL を直してください。

使うアプリと項目

受注（ボタンを置くアプリ）

項目名	項目コード	種類	メモ
受注番号	受注番号	文字列（1行）	値の重複を禁止する（合計金額を書き込むときの目印）
顧客名	顧客名	文字列（1行）
受注日	受注日	日付
納期	納期	日付
ステータス	受注ステータス	ドロップダウン	受付 / 手配中 / 出荷済 / 完了
合計金額	合計金額	数値	明細から集計して書き込む

受注明細

項目名	項目コード	種類	メモ
受注番号	受注番号	文字列（1行）	受注と結び付ける
商品名	商品名	文字列（1行）
単価	単価	数値
数量	数量	数値
小計	小計	計算（単価 * 数量）	計算の項目なので SQL では書き込まない

ステータスの項目コードを「ステータス」にしていないのは、kintone のアプリには最初から、プロセス管理の「ステータス」（項目コードも「ステータス」）があるためです。プロセス管理を使わなくても消えないので、同じコードの項目は作れません。

変えるところ

• 論理アプリの表（「受注」「受注明細」）を、自分のアプリに向ける
• パラメーター expect_app の式を、ボタンを置くアプリの番号にする（下の「気をつけること」）
• アプリをコピーして使うときは、expect_app と論理アプリの参照先を両方そろえて直す（片方だけでは守れない）
• 項目コードが違えば、SQL の項目を直す
• 入れ直すデータ（受注番号・顧客名・商品・日付の決め方）は、SQL の中の値を書き換える

気をつけること

• 2 つのアプリの全レコードを消します。 デモ用のアプリでだけ使ってください。消したデータは戻せません。
• アプリをコピーすると、プラグインの設定も一緒に写ります。 コピーしたアプリでボタンを押すと、元のデモデータが消えてしまいます。それを防ぐため、SQL の最初で「押したアプリの番号」と「設定に書いた番号」を比べて、違えば何もせずに止めます。テンプレートから作り直したときも番号が変わるので、expect_app の式を直してください。
  ただし、この照合が確かめるのは「押したアプリ」と expect_app が同じかどうかだけです。論理アプリ「受注」「受注明細」がどのアプリを指しているかは見ません。expect_app だけ直して論理アプリを直し忘れると、元のアプリのデータを消します。コピーしたアプリで使うときは、両方を必ず確かめてください。
• 途中で止まったときは、それまでに書いた分が残ります（まとめて取り消す仕組みはありません）。止まった場所ごとに、残り得る状態は次のとおりです。

止まった場所	残り得る状態
アプリの番号・［はい］の照合	何も変わらない（書き込む前に止まる）
明細を消すところ	前の明細が、全部または一部残る
受注を消すところ	明細は消えている。前の受注が、全部または一部残る
受注を入れるところ	受注が無い、または一部だけ入っている
明細を入れるところ	受注は入っている。明細が無い、または一部だけ入っている
合計金額を書き込むところ	受注と明細は入っている。合計金額が空、または一部だけ入っている

書き込みの上限を超えるときだけは、その文を書く前に止まります（その文で消したり入れたりするのは 0 件）。

• 止まった原因を取り除いてから押し直すと、残ったデータを消して最初から作り直します。 押すたびに、先に全件を消してから入れ直すためです。権限が足りない、書き込みの上限を超えた、などの原因は、押し直すだけでは直りません。
• 書き込みの上限は 1,000 件にしています。 1 回に書き込むのは、押す前の 2 つのアプリのレコード数の合計を N として N ＋ 21 件（消す N 件・入れる 16 件・合計金額 5 件）です。2 回目からは N = 16 なので 37 件です。デモでレコードを増やして N が 979 件を超えると上限で止まり、消したあとで止まることもあります（上の表のとおり、途中までの状態が残ります）。レコードを増やして使うなら、先に上限を上げておいてください。
• 押せる人は絞っていません。 絞るなら、設定の「実行を許す人」にユーザーやグループを入れます（押し間違いを防ぐためのもので、本当の守りは kintone のアクセス権です）。
• ログアプリを設定していないので、2 人が同時に押すと止められません。デモの前に押すのは 1 人に決めておきます。

設定の要点

設定	値
種類	アプリ（レコードを選ばずに動く）
出し方	一覧のパネル（区分なし）
論理アプリ	受注 = ボタンを置くアプリ、受注明細 = 明細のアプリ
パラメーター	expect_app（計算式。例 "1234" = ボタンを置くアプリの番号）、ok（実行時に聞く）
入力項目	ok: ラベル「デモデータを初期化します。よろしいですか？」、選択肢「はい」だけ、必須
確認	オフ（確かめは上の入力 1 回だけ）
書き込みの上限	1,000 件
結果メッセージ	計算式（下）

結果メッセージの計算式です。うまくいかなかったときは、原因を取り除いてから押し直せばよいことを出します。

IF($result_status = "success",
   "デモデータを初期化しました（削除 " & $result_deleted & " 件・登録 " & $result_inserted & " 件・合計金額の更新 " & $result_updated & " 件）",
   "デモデータの初期化は終わっていません（" & $result_status & "）。原因を取り除いてから押し直すと、はじめからやり直します。")

「確認」をオンにすると、書き込む文ごとに件数の確認が出ます（この事例では、入力ダイアログと合わせて 6 回押すことになりました）。押す人が決まっているデモの用途なので、オフにして、確かめは入力ダイアログの 1 回にしました。オフにするときは書き込みの上限が必須です。

SQL の全文

-- @ksql dialect: 1
-- デモデータ初期化: 明細 → 受注の順に全件を消し、実行日を基準にした日付でシードを入れ直す
DECLARE @_app = '';
DECLARE @expect_app = '';
DECLARE @ok = '';

-- 誤爆の防止: 設定を書いたアプリ（受注（デモ））以外では動かさない（アプリをコピーしたときなど）
ASSERT @_app = @expect_app, 'このアプリではデモデータを初期化できません（アプリの番号が設定と違います）';
ASSERT @ok = 'はい', '確認で「はい」が選ばれていません';

-- 既存データの削除（子 → 親）。WHERE $id > 0 は「全件」の意図を書いたもの
DELETE FROM LAPP_受注明細 WHERE $id > 0;
DELETE FROM LAPP_受注 WHERE $id > 0;

-- 受注のシード。日付は実行日（@TODAY()）が基準。当月分は月初（@MONTH_START()）より前にしない
CREATE TEMP TABLE #seed AS
SELECT 'DEMO-001' AS 受注番号, 'サンプル商事' AS 顧客名, @TODAY() AS 受注日, DATE_ADD(@TODAY(), 7, 'DAY') AS 納期, '受付' AS 受注ステータス
UNION ALL
SELECT 'DEMO-002' AS 受注番号, 'テスト工業' AS 顧客名, GREATEST(DATE_ADD(@TODAY(), -3, 'DAY'), @MONTH_START()) AS 受注日, DATE_ADD(@TODAY(), 4, 'DAY') AS 納期, '手配中' AS 受注ステータス
UNION ALL
SELECT 'DEMO-003' AS 受注番号, 'デモ物産' AS 顧客名, GREATEST(DATE_ADD(@TODAY(), -15, 'DAY'), @MONTH_START()) AS 受注日, DATE_ADD(GREATEST(DATE_ADD(@TODAY(), -15, 'DAY'), @MONTH_START()), 10, 'DAY') AS 納期, '出荷済' AS 受注ステータス
UNION ALL
SELECT 'DEMO-004' AS 受注番号, '見本産業' AS 顧客名, @MONTH_START() AS 受注日, DATE_ADD(@MONTH_START(), 14, 'DAY') AS 納期, '完了' AS 受注ステータス
UNION ALL
SELECT 'DEMO-005' AS 受注番号, 'サンプル商事' AS 顧客名, DATE_ADD(@TODAY(), -1, 'MONTH') AS 受注日, DATE_ADD(DATE_ADD(@TODAY(), -1, 'MONTH'), 7, 'DAY') AS 納期, '完了' AS 受注ステータス;

INSERT INTO LAPP_受注 (受注番号, 顧客名, 受注日, 納期, 受注ステータス)
SELECT 受注番号, 顧客名, 受注日, 納期, 受注ステータス FROM #seed;

-- 明細のシード（受注番号で受注と結ぶ。小計は計算の項目なので書かない）
INSERT INTO LAPP_受注明細 (受注番号, 商品名, 単価, 数量) VALUES
('DEMO-001', 'A4 コピー用紙', 500, 10),
('DEMO-001', 'ボールペン（黒）', 120, 20),
('DEMO-002', 'ノートパソコン', 98000, 2),
('DEMO-002', 'マウス', 2500, 2),
('DEMO-003', 'オフィスチェア', 32000, 3),
('DEMO-003', 'デスク', 45000, 3),
('DEMO-003', '書類ケース', 1800, 6),
('DEMO-004', 'プリンター用トナー', 8500, 4),
('DEMO-004', 'クリアファイル', 300, 50),
('DEMO-005', 'A4 コピー用紙', 500, 8),
('DEMO-005', '付箋', 250, 12);

-- 仕上げ: 明細の小計を受注番号で集計して、受注の合計金額に書き戻す
UPSERT INTO LAPP_受注 (受注番号, 合計金額)
SELECT 受注番号, SUM(小計) AS 合計金額
  FROM LAPP_受注明細
 WHERE 受注番号 IN ('DEMO-001', 'DEMO-002', 'DEMO-003', 'DEMO-004', 'DEMO-005')
 GROUP BY 受注番号
ON DUPLICATE (受注番号);

読むときのポイントです。

• @TODAY() と @MONTH_START() は、押した日と、その月の 1 日です。1 回の実行の中では同じ値なので、文によって日付がずれることはありません。
• GREATEST(…, @MONTH_START()) で、「3 日前・15 日前」が月初より前になるときに月初にそろえています（日付は「年-月-日」の文字なので、大きいほうが新しい日です）。
• ASSERT は、条件が合わなければそこで止める文です。ここでは書き込む前に 2 つ確かめています。
• DELETE には条件が必須です。全件を消したいときも WHERE $id > 0 と書いて、全件のつもりであることを示します。
• UPSERT … ON DUPLICATE (受注番号) は、受注番号が同じ受注があれば上書きします。受注番号に「値の重複を禁止する」が要るのはこのためです。

AI への頼み方

この設定は、AI（Claude Code）に kSQL アクションのオーサリングツール（kact）を使わせて作りました。渡した依頼の文の主な部分です。

kSQL アクションプラグインの設定ファイル（kact）を作成してください。アプリは新規作成。

【目的】
デモ環境のデータをいつでも初期状態へリセットできる「デモデータ初期化」アクションを定義します。
固定日付ではなく実行日（当日）を基準にした相対日付でシードデータを投入する構成にしてください。

【対象アプリ】
- 受注アプリ（親）: 受注番号, 顧客名, 受注日, 納期, ステータス, 合計金額
- 受注明細アプリ（子）: 受注番号, 商品名, 単価, 数量, 小計

【実装要件】
1. 確認ダイアログ「デモデータを初期化します。よろしいですか？」、実行できる人の制限、対象アプリ ID の確認
2. 既存データの削除（子 → 親の順）
3. 当日・当日 - 3 日・当日 - 15 日・当日 + 7 日 などの相対日付で、当月分（ステータス混在）と先月分を 3〜5 件
4. 合計金額の集計、完了通知と画面の更新

【進め方】
不明な点は設定ファイルを作る前に質問すること。作成後は検査を実行し、未検査の項目を報告すること。

AI が聞き返したこと（4 つをまとめて聞かれました）

聞かれたこと	答え
アプリはどうするか（kact はアプリを作れない）	先に作る
項目と日付の案。月の前半に押すと「15 日前」が先月に入るので、月初にそろえてよいか	その案で
ボタンを出す人を絞るか	絞らない
確認の出し方。本体の確認ダイアログは文を変えられないので、入力ダイアログで［はい］を選ばせてよいか	その案で

AI が自分で決めて、作る前に伝えたこと

• アプリをコピーしたときに元のデータを消さないよう、アプリの番号を比べる ASSERT を入れる
• 書き込みの上限を 1,000 件にする

依頼とできあがりの対応

依頼	できあがり
確認ダイアログ	入力ダイアログで［はい］を選ぶ（本体の確認の文は変えられないため）
実行できる人の制限	付けない（聞き返して決めた）
対象アプリ ID の確認	ASSERT で、押したアプリの番号と expect_app を比べる（論理アプリの参照先は見ない）
子 → 親の順の削除	明細 → 受注の順に、全件を消す
相対日付で 3〜5 件	押した日と月初から計算して、受注 5 件・明細 11 件
合計金額の集計	明細の小計を受注番号ごとに足して、受注に書き戻す
完了通知と画面の更新	結果メッセージで件数を出し、完了のダイアログに［画面を更新］を出す（押すと読み直す）

作った後に AI がしたこと

• 設定の検査（エラー 0、注意 2）と、文ごとの実行計画の確認
• 日付の式は計算式の試しでは確かめられないので、手元の kSQL で、押す日を変えて評価した

実機で押してから変えたこと

• 「確認」をオンにしていたら、書き込む文ごとに確認が出て、何度も押すことになった → 「確認」をオフにして、確かめは入力ダイアログの 1 回にした

今回は、依頼の文の「不明な点は作る前に質問する」に沿って、作る前に 4 点を確かめてきました。依頼の文を自分の業務に合わせて書き換えて、同じ手順で試せます。

詳しい記事

• 一覧のパネルにボタンを出す: ⑩ 画面のどこに出すか
• 入力ダイアログ・確認・書き込みの上限: ① 詳細画面編・④ 運用編
• 集計して書き戻す形: ③ 集計編
• 設定を AI に作ってもらう: ⑦ オーサリング編・⑫ オーサリング改善編

関連記事

• rex0220 kSQL アクションプラグイン（概要）
• 事例集（やりたいことから探す）

機能ごとの記事: 概要 / ① 詳細画面 / ② 一覧 / ③ 集計 / ④ 運用 / ⑤ 事例 / ⑥ イベント / ⑦ オーサリング / ⑧ 請求データ / ⑨ 締めの画面 / ⑩ どこに出すか / ⑪ 多言語 / ⑫ オーサリング改善