【テクニカル・上級編】Notionの「データベース・テンプレート」における変数（@Todayや@Me）の動的置換バグと、自動化フローが意図せず停止する原因の特定方法 – プロジェクト・ナレッジ管理活用バイブル

Notionデータベース・テンプレートの暗黒面：動的変数バグの解剖と、自動化パイプラインを死守するアーキテクチャ設計

エンジニアリング組織のスケールに伴い、Notionを単なる「綺麗なWiki」から、JiraやConfluence、そして社内ニッチツール群を統合した「開発オペレーションの中枢（SoR）」へと昇華させているチームは多いだろう。

しかし、データベース・テンプレートとオートメーション（Automations）を高度に組み合わせた瞬間、私たちはNotionの内部アーキテクチャが持つ「厄介な仕様の壁」に激突する。

特に、`@Today`や`@Me`といった動的変数が、テンプレート展開時やAPI経由の自動化フックにおいて意図せず「静的な値」にハードコードされるバグ（あるいは仕様の罠）は、多くのDevOpsエンジニアやナレッジマネージャーの夜を眠れぬものにしているはずだ。

本稿では、この現象の根本原因をNotionの内部データモデルのレイヤから解き明かし、ワークフローの静止を防ぐための極限の設計プラクティスを提示する。

—

1. データベーステンプレート内動的変数の「仕様の罠」と実例

発生する現象

プロジェクト管理やインシデント管理のデータベースにおいて、次のようなテンプレートを運用していると仮定しよう。

  • テンプレート名: `[P0] 緊急インシデント起票`
  • プロパティ設定:
  • ステータス: `Triage`
  • 担当者: `@Me`（実行ユーザーに動的置換される想定）
  • 期限: `@Today`（生成日の日付に動的置換される想定）

通常、手動でこのテンプレートを適用した場合は意図通りに展開される。しかし、Notionの「Automations（自動化）」機能、あるいは外部API（Notion API /pages エンドポイント）からデータベースページを自動生成した瞬間、この動的変数が破壊される。

根本原因：評価フェーズの断絶

Notionのバックエンドアーキテクチャにおいて、データベース・テンプレートの展開は「クライアントサイド（UI）でのレンダリング時」と「サーバーサイド（Automations / API）での非同期実行時」で評価エンジンが異なる。

1. UI起因の展開: ユーザーがブラウザやアプリで明示的にテンプレートをクリックした際、フロントエンドのコンテキスト（当前のセッションユーザーID、ブラウザのローカルタイム）がペイロードにバインドされ、`@Me` や `@Today` が動的に解決される。
2. Automations / API起因の展開: サーバーサイドのワーカープロセスがトリガーを検知してページを生成する。この時、「誰が実行したか（@Meの解決対象）」のセッションコンテキストが存在しない。さらに、タイムゾーンの解決がUTC基準でミリ秒単位のズレを生むか、あるいはテンプレート作成時点のタイムスタンプ評価がそのままスナップショット（固定化）される。

結果として、テンプレート内の `@Today` は「テンプレートが作成された日（あるいはオートメーションがシステムキャッシュを保持した日）」の固定値としてベタ書きされ、`@Me` は `null` またはシステムBotのIDに化けることになる。

—

2. オートメーションとテンプレートの衝突回避策：APIとスクリプトによるバイパス設計

Notion標準のAutomations機能は、複雑な条件分岐や動的変数の制御においてまだ脆弱性（あるいは機能不足）を抱えている。本番環境のパイプラインでデータの整合性を担保するためには、「Notion標準のテンプレート機能に頼らず、API経由でペイロードを動的に組み立ててインジェクションする」というアプローチが最も確実でスケーラブルである。

ここでは、Node.js（TypeScript）と公式SDKを用い、動的変数（今日の日付と実行者）を完全にコントロールしてページを動的生成する堅牢なスクリプトの例を示す。

堅牢なページ生成スクリプト（TypeScript）

import { Client } from “@notionhq/client”;

// 初期化（環境変数からセキュアにトークンを読み込み）
const notion = new Client({ auth: process.env.NOTION_API_KEY });

interface CreateIncidentParams {
databaseId: string;
incidentTitle: string;
reporterUserId: string; // 実行者のNotion User ID
}

/

  • テンプレート機能に依存せず、動的変数を解決した上でページをプログラムmaticallyに生成する

/
async function createDynamicIncidentPage({
databaseId,
incidentTitle,
reporterUserId,
}: CreateIncidentParams): Promise {
try {
// 1. 動的変数の評価（Runtime Evaluation）
const nowJST = new Date().toLocaleString(“en-US”, {
timeZone: “Asia/Tokyo”,
});
const todayStr = new Date(nowJST).toISOString().split(“T”)[0]; // “YYYY-MM-DD”

// 2. Notion APIペイロードの構築
const response = await notion.pages.create({
parent: { database_id: databaseId },
properties: {
// タイトル
“Incident Name”: {
title: [
{
text: { content: `[P0] ${incidentTitle}` },
},
],
},
// ステータス
Status: {
status: { name: “Triage” },
},
// 動的変数 @Me の代替：明示的にユーザーIDを指定
Assignee: {
people: [{ id: reporterUserId }],
},
// 動的変数 @Today の代替：厳密にJSTで計算した日付を挿入
DueDate: {
date: { start: todayStr },
},
},
// 3. 本文（Body）側にも動的変数を反映したブロック構造を流し込む
children: [
{
object: “block”,
type: “heading_2”,
heading_2: {
rich_text: [{ type: “text”, text: { content: “自動生成インシデントレポート” } }],
},
},
{
object: “block”,
type: “paragraph”,
paragraph: {
rich_text: [
{
type: “text”,
text: { content: `起票日時 (JST): ${nowJST}\n` },
},
{
type: “text”,
text: { content: “ステータスおよび担当者は自動アサインされました。” },
},
],
},
},
],
});

console.log(`[Success] Page created successfully. ID: ${response.id}`);
} catch (error) {
console.error(“[Error] Failed to create dynamic incident page:”, error);
process.exit(1);
}
}

// 実行例
// createDynamicIncidentPage({
// databaseId: process.env.INCIDENT_DB_ID!,
// incidentTitle: “API Gateway 502 Bad Gateway Spike”,
// reporterUserId: “user-uuid-here”,
// });

このアプローチをとることで、NotionのGUIオートメーションが持つ「変数の固定化バグ」を完全に回避し、インフラストラクチャ側（GitHub ActionsやAWS Lambdaなど）で正確なタイムスタンプとユーザーコンテキストを注入することが可能になる。

—

3. 安定したワークフローを維持するための設計ベストプラクティス

組織全体でNotionのデータベースと自動化をスケールさせるにあたり、ナレッジのサイロ化を防ぎ、ワークフローの突然死を回避するためのアーキテクチャ原則を以下に定義する。

1. 「テンプレート内の動的変数」の利用を原則禁止する

チームメンバーに対し、自動化（Automations）のトリガーによって作成されることが前提となっているデータベース・テンプレートにおいて、`@Today` や `@Me` をプロパティやページ本文に直置きしないようガイドラインを徹底する。

  • 代替案: プロパティのデフォルト値機能、あるいは前述のAPI/Webhook駆動のパイプラインに処理をオフロードする。

2. オートメーションの「トリガーの連鎖（Cascade）」を排除する

「データベースAのステータス変更 ➔ データベースBにページ作成 ➔ データベースCを更新」といった、Notion内でのオートメーションの多段連鎖はデバッグを極端に困難にする。

  • 原則: Notionのオートメーションは「単一のシンプルな通知やプロパティ更新」にとどめ、複雑なビジネスロジックやページ間リレーションの構築は、外部の iPaaS（Zapier, Make）や自前のサーバーレスワーカー（AWS Lambda / Cloudflare Workers）にWebhookを飛ばしてハンドリングする。

3. APIリミットとパフォーマンスの最適化

Notion APIには「平均3回/秒（バーストを考慮しても一定の制限）」というレートリミットが存在する。大量のデータベース項目を一括操作するようなバッチ処理をNotion上で直接組むと、あっさり `429 Too Many Requests` に叩かれる。

  • ハック: 外部ワーカー側でキューイング機構（AWS SQSやRedis等）を挟み、指数バックオフ（Exponential Backoff）を用いたリトライロジックを必ず実装すること。

—

結び

Notionは、その極めて高い柔軟性とモダンなUIゆえに「何でもできる錯覚」を私たちに抱かせる。しかし、その内実を覗けば、分散システム特有のコンテキストの欠落や、非同期処理における状態の固定化といった泥臭い課題が眠っている。

ツールの仕様に振り回されるのではなく、ツールの限界値を正確に把握し、APIやコードによる適切なレイヤリング（抽象化）を行うこと。それこそが、開発チームのベロシティを極限まで高める真のナレッジエンジニアリングである。

スポンサーリンク
タイトルとURLをコピーしました