템플릿 기반 HTML 이메일 알림 보내기

Notify Via Email 단계는 워크플로의 테이블 하나 이상을 대상으로 렌더링되는 Jinja 템플릿으로 이메일을 풍부한 HTML 보고서 형태로 작성합니다. 각 테이블을 이름이 지정된 프레임으로 단계에 추가하면, 템플릿이 해당 프레임을 하나의 이메일로 렌더링합니다. 이 단계는 곧바로 Jinja 편집기로 열리며, 이것이 유일한 작성 화면입니다. 일반 텍스트 본문 상자도, 전환할 모드도 없습니다. 이 가이드에서는 편집기와 서식 도구 모음, 추가하는 프레임, 템플릿 안에서 사용할 수 있는 데이터, render_table 도우미, 이메일 전송에 따르는 제약을 설명합니다.

Jinja 편집기

Notify Via Email 단계를 열면 Jinja 편집기가 나타납니다. 프레임을 하나 이상 추가하고(아래 참조) 본문에 템플릿을 작성하면, 입력하는 동안 오른쪽의 실시간 미리 보기가 업데이트됩니다. 나에게 테스트 보내기는 렌더링된 이메일을 본인 주소로 전송하므로, 워크플로를 예약하기 전에 확인할 수 있습니다. 새 단계는 Jinja 전용입니다. 채워야 할 일반 텍스트 본문도 없고, 서식 있는 텍스트와 일반 텍스트 사이의 전환도 없습니다.

참고

편집기에는 샌드박스 방식의 자체 렌더링 엔진이 있습니다. 이 엔진은 Export Templated 단계와 구문이 비슷하지만(Jinja, 이름이 지정된 프레임, render_table 도우미) 두 엔진은 서로 호환되지 않습니다. 한쪽을 위해 작성한 템플릿은 다른 쪽에서 실행되지 않습니다.

서식 도구 모음

Jinja 편집기에는 반복되는 코드를 직접 입력하지 않고 템플릿을 구성할 수 있는 도구 모음이 있습니다.

• 코드 정리는 전체 템플릿의 들여쓰기를 다시 맞추고 정규화합니다. 일관된 들여쓰기, 태그 간격, Jinja 블록 레이아웃을 적용하므로 계속 편집해 온 템플릿도 깔끔하게 읽힙니다. 형식만 바꾸며 템플릿이 렌더링하는 내용은 바꾸지 않습니다.
• 삽입은 커서 위치에 미리 만들어진 스니펫을 넣습니다. 프레임에 맞게 미리 채워진 render_table(...) 호출, 워크스페이스 이름 {{ cloud }}, 프로젝트 변수 또는 워크플로 변수, 프레임의 행 수, 프레임의 행에 대한 {% for %} 루프, if/else 및 주석 틀을 삽입할 수 있습니다.
• 형식은 커서 위치의 값에 표시 필터를 적용합니다. 통화, 천 단위 구분, 백분율, 반올림, 날짜 형식과 함께 텍스트 도우미(대문자, 소문자, 제목 형식, 공백 제거), 목록 도우미(길이, 결합, 합계 등)를 제공합니다.
• 스타일은 선택한 텍스트를 HTML 서식으로 감쌉니다. 굵게, 기울임꼴, 밑줄, 세 가지 크기의 제목, 단락, 글머리 기호 및 번호 매기기 목록, 블록 인용, 링크, 줄 바꿈을 지원합니다. 모든 옵션은 이메일 새니타이저가 유지하는 마크업만 생성하므로(허용 목록 HTML 제약 참조), 제목은 h1이 아니라 더 크고 굵은 줄로 표시되며 밑줄은 허용된 태그를 사용합니다.

모든 버튼은 직접 입력할 수 있는 텍스트를 삽입할 뿐입니다. 시작점으로 사용하고 자유롭게 편집하십시오.

프레임 추가

단계는 프레임을 기준으로 보고합니다. 프레임은 단계에 추가하는, 이름이 지정된 단일 테이블 선택입니다. 프레임을 하나 또는 여러 개 추가할 수 있으며, 각 프레임은 동일한 이메일로 렌더링됩니다. 각 프레임에는 다음을 지정합니다.

• 프레임 이름: 템플릿에서 프레임을 참조하는 데 사용하는 레이블입니다(Sales, Overdue 등).
• 워크플로 컨텍스트의 테이블 하나
• 해당 테이블에 대한 선택적 열 선택, where 필터, 집계

프레임은 항상 단일 테이블입니다. 테이블을 조인하거나 결합해 하나의 프레임으로 만드는 것은 지원되지 않습니다. 대신 프레임을 하나 더 추가하고 각각 이름으로 참조하십시오.

각 프레임은 템플릿 안에서 frames['<Frame Name>']을 통해 노출되며, 이는 해당 프레임의 rows와 columns를 포함합니다(아래 참조).

템플릿 안에서 사용할 수 있는 항목

템플릿은 제한적이고 명시적인 변수 집합을 노출합니다. 정의되지 않은 변수를 참조하면 렌더링이 실패하므로 여기에 나열된 것만 사용하십시오.

변수	내용
cloud	워크스페이스 이름입니다.
frames	프레임 이름을 키로 하는 프레임 사전입니다. frames['Sales'].rows는 해당 프레임의 행 개체 목록(행마다 하나)이고, 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) }}

한 번의 호출로 해당 프레임에 대한 올바른 구조의 HTML 테이블이 생성됩니다. 표시하려는 프레임마다 한 번씩 호출하십시오.

단일 프레임 템플릿에서는 첫 번째 프레임에 바인딩된 최상위 rows와 columns를 사용할 수 있습니다.

{{ render_table(rows, columns) }}

전체 예제

이 템플릿에는 Overdue와 Paid라는 두 개의 프레임이 있습니다. 워크스페이스 이름, 짧은 요약 줄, 각 프레임의 테이블을 렌더링합니다.

<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 %}

각 프레임이 보고할 테이블을 가리키도록 설정하면, 렌더링된 이메일에는 굵은 제목 줄, 행 수로 계산된 한 줄 요약, 프레임마다 하나의 테이블이 표시됩니다. 프레임이 하나뿐이라면 같은 템플릿을 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} 치환