テンプレートを使ったHTMLメール通知の送信

Notify Via Email ステップは、ワークフローの1つ以上のテーブルに対してJinjaテンプレートをレンダリングし、リッチなHTMLレポートとしてメールを作成します。各テーブルを名前付きのフレームとしてステップに追加すると、テンプレートがそれらのフレームを1通のメールにレンダリングします。このステップは直接Jinjaエディターで開き、それが唯一の作成画面です。プレーンテキストの本文ボックスも、切り替えるモードもありません。このガイドでは、エディターとその書式設定ツールバー、追加するフレーム、テンプレート内で使用できるデータ、render_table ヘルパー、そしてメール送信に伴う制約について説明します。

Jinjaエディター

Notify Via Email ステップを開くと、Jinjaエディターが表示されます。1つ以上のフレーム（後述）を追加し、本文にテンプレートを記述すると、入力に合わせて右側のライブプレビューが更新されます。自分にテスト送信を使うと、レンダリングされたメールが自分のアドレスに送信されるので、ワークフローをスケジュールする前に確認できます。新しいステップはJinja専用です。入力するプレーンテキストの本文はなく、リッチとプレーンの切り替えもありません。

書式設定ツールバー

Jinjaエディターには、定型コードを手入力せずにテンプレートを整えるためのツールバーがあります。

整形は、テンプレート全体のインデント、タグの間隔、Jinjaブロックのレイアウトを統一して整え直し、編集を重ねたテンプレートを読みやすくします。整形するだけで、テンプレートのレンダリング結果は変わりません。
挿入は、あらかじめ用意されたスニペットをカーソル位置に挿入します。フレーム用に入力済みの render_table(...) 呼び出し、ワークスペース名 {{ cloud }}、プロジェクト変数やワークフロー変数、フレームの行数、フレームの行を回す {% for %} ループ、if/else やコメントの雛形などがあります。
形式は、カーソル位置の値に表示フィルターを適用します。通貨、桁区切り、パーセント、丸め、日付の形式のほか、テキストヘルパー（大文字、小文字、タイトルケース、トリム）やリストヘルパー（長さ、結合、合計など）があります。
スタイルは、選択したテキストをHTMLの書式で囲みます。太字、斜体、下線、3種類の見出しサイズ、段落、箇条書きと番号付きリスト、引用ブロック、リンク、改行があります。どのオプションも、メールのサニタイザーが残すマークアップだけを出力します（許可リストにあるHTMLの制約を参照）。そのため、見出しは h1 ではなく大きめの太字の行として表示され、下線は許可されたタグで実現されます。

どのボタンも、自分で入力できるテキストを挿入するだけです。出発点として使い、自由に編集してください。

フレームを追加する

ステップは、ステップに追加する名前付きの単一テーブル選択であるフレームに基づいてレポートを作成します。フレームは1つでも複数でも追加でき、それぞれが同じメールにレンダリングされます。フレームごとに、次を指定します。

フレーム名 — テンプレート内で参照するときのラベルです（Sales、Overdue など）。
ワークフローのコンテキストにある1つのテーブル
任意の列の選択、where フィルター、そのテーブルに対する集計

フレームは常に1つのテーブルです。テーブルを結合したり組み合わせたりして1つのフレームにすることはできません。代わりに2つ目のフレームを追加し、それぞれを名前で参照してください。

各フレームは、テンプレート内で frames['<Frame Name>'] として公開され、そのフレームの rows と columns を保持しています（後述）。

テンプレート内で使用できるもの

テンプレートには、限定された明示的な変数のセットが公開されます。未定義の変数を参照するとレンダリングが失敗するため、ここに記載されているものだけを使用してください。

変数	内容
`cloud`	ワークスペース名。
`frames`	フレーム名をキーとする、フレームの辞書。`frames['Sales'].rows` はそのフレームの行オブジェクト（1行につき1つ）のリスト、`frames['Sales'].columns` は順序どおりの列のリストです。
`rows`	最初のフレームの行。単一フレームのテンプレートで `rows` を直接使えるようにするための便宜的なバインディングです。
`columns`	最初のフレームの列。`rows` と同じ便宜的なバインディングです。
`variables`	プロジェクトの変数と、ワークフロー内ではワークフローの変数を、名前をキーとして保持します（`variables['Fiscal Year']`）。組み込みの `variables['project']`、`variables['model']`、`variables['date']`（現在のUTC時刻）もここにあります。変数名が有効な識別子であるとは限らないため、添字形式を使用してください。

値はPythonのネイティブな型のまま保持されます。Decimal は Decimal のまま、日付は日付のまま、null の列は None として渡されます。そのため、文字列化されたテキストではなく、Pythonと同じ方法で書式設定や比較ができます。

`render_table` でテーブルをレンダリングする

<table> マークアップを手書きする代わりに、フレームの行と列を指定して render_table マクロを呼び出します。各フレームは名前で参照します。

{{ render_table(frames['Sales'].rows, frames['Sales'].columns) }}

1回の呼び出しで、そのフレームに対して正しく構造化されたHTMLテーブルが出力されます。表示したいフレームごとに1回ずつ呼び出してください。

単一フレームのテンプレートでは、最初のフレームにバインドされたトップレベルの rows と columns を使用できます。

{{ render_table(rows, columns) }}

完全な例

このテンプレートには、Overdue と Paid の2つのフレームがあります。ワークスペース名、短いサマリー行、そして各フレームのテーブルをレンダリングします。

<p><strong>Invoice Status — {{ cloud }}</strong></p>

<p>{{ frames['Overdue'].rows|length }} invoice(s) are past due as of today.</p>

{{ render_table(frames['Overdue'].rows, frames['Overdue'].columns) }}

<p><strong>Recently Paid</strong></p>

{{ render_table(frames['Paid'].rows, frames['Paid'].columns) }}

{% if frames['Overdue'].rows|length == 0 %}
<p>No overdue invoices — nothing further to review.</p>
{% endif %}

各フレームをレポートしたいテーブルに向けると、レンダリングされたメールには、太字のタイトル行、行数から計算された1行のサマリー、そしてフレームごとのテーブルが表示されます。フレームが1つの場合は、同じテンプレートを、フレーム名を使わずに rows と columns で記述することもできます。

許可リストにあるHTMLの制約

レンダリングされたメールはすべて、送信前に、PlaidCloudのほかのトランザクションメールと同じサニタイザーを通過します。サニタイザーは、小さな許可リストにないものをすべて削除します。

許可されるタグ: render_table が出力するテーブルタグ（table、tbody、tr、th、td）と、一般的なテキストタグ（p、br、strong/b、em/i、ul/ol/li、blockquote、code、a）です。見出し（h1～h6）、div、span はリストに含まれません。タイトルには、strong を中に入れた p を使用してください。
許可される属性: class と style のみです（a には href も許可されます）。
<thead> は使えません。 render_table は table / tbody / tr / th / td を出力します。ヘッダー行は、別個の <thead> セクションではなく、tbody 内の th セルで構成された tr です。
<style> ブロックは使えません。また外部リソースも使えません。url(...) 参照やトラッキングビーコンは、リストにないほかのタグや属性と同様に削除されます。

実際には、レポートの構造は render_table とプレーンなテキストタグで構築し、カスタムスタイルはシンプルなインラインの style 属性にとどめてください。<style> ブロック、外部スタイルシート、カスタムフォント、トラッキングピクセルなど、それ以上に凝ったものはサニタイズで除去され、配信されるメールには表示されません。

既存のステップとレガシーステップ

Jinjaでの作成に対応する前に作成されたステップは、古い本文が変換された状態で、そのままエディターで開きます。{project}、{model}、{cloud}、{date} で構成された標準的なプレーンテキストの本文は、Jinja形式（{{ project }}、{{ cloud }} など）に書き換えられるため、そこから編集を続けられます。

コンバーターが安全に書き換えられない本文（標準外のトークンや、波かっこの不一致など）は、プレーンテキストのフォールバックボックスに残ります。そのステップは、以前と同じようにレガシーの {token} 置換で送信し続け、作成画面だけがプレーンテキストのままになります。新しいステップがこの経路を使うことはありません。

エディターは入力中に変数名をチェックし、解決されないものにフラグを付けます。レガシーの本文から引き継がれた {{ project }}、{{ model }}、{{ date }} は、現在は variables 経由でのみ解決されるため、フラグが付きます。variables['project']、variables['model']、variables['date'] を使うか、トークンをフレームのいずれかの列に置き換えるか、保存する前に削除してください。

セキュリティと送信

フレームの読み取りは、プロジェクト内のほかの読み取りと同じ行レベルセキュリティを通ります。フレームは、実行中のユーザーまたは自動化プリンシパルが閲覧を許可されている行だけを返します。送信の制限（受信者、サイズ、レート）はプレーンテキストの場合から変わりません。テンプレートモードによって、制限が緩和されたり追加されたりすることはありません。

次のステップ

Notify Via Email のリファレンス — フィールドレベルの設定
Export Templated — テーブルからドキュメントをレンダリングする、形は似ていますが別のエンジン
ワークフロー変数の管理 — レガシーのプレーンテキスト本文が引き続き使用する {var} 置換