Umitake ドキュメントジェネレーター for kintone ユーザーマニュアル

目次

1. 概要
2. インストール
3. プラグイン設定
   • ドキュメント設定の追加
   • テンプレートソース
   • 出力先
   • ファイル名テンプレート
   • 出力トリガー
4. テンプレートの準備
   • DOCXテンプレート
   • XLSXテンプレート
   • PDFテンプレート
5. テンプレートタグ仕様
   • オプション一覧
   • 基本タグ
   • 日付フォーマット
   • 通貨フォーマット
   • 数値フォーマット
   • 生成日付・日時タグ
   • 条件付きプレフィックス・サフィックス
   • 配列フィールドの出力
   • 画像差し込み
   • QRコード・バーコード
   • 条件分岐ブロック（IF/IFEXIST）
   • サブテーブルのループ展開
   • 関連レコードのループ展開
6. ドキュメントの生成
   • ボタンで生成する場合
   • ステータス変更で生成する場合
   • 一覧画面から一括生成する場合
7. ラベル印刷
   • ラベル印刷設定の追加
   • テンプレートの準備（ラベル印刷）
   • 一覧画面からの生成（ラベル印刷）
8. 注意事項・制限
9. トラブルシューティング

概要

ドキュメントジェネレーター プラグインは、kintoneのレコードデータをもとに Word（DOCX）・Excel（XLSX）・PDF ドキュメントを自動生成するプラグインです。

主な機能:

• レコードのフィールド値をテンプレートに差し込んで出力
• サブテーブルフィールドのループ展開
• 関連レコード一覧フィールドのループ展開（DOCX / PDF はネストループも対応）
• 日付・通貨・数値の書式指定
• 出力ファイルを同一アプリまたは別アプリの添付フィールドに保存
• ボタンクリックまたはステータス変更による出力トリガー
• レコード一覧画面からの一括出力（絞り込み条件に一致するすべてのレコードを処理）
• 複数レコードをDOCXラベルシートにまとめて出力するラベル印刷（1シートあたりN件、ZIPで一括ダウンロード）

インストール

1. kintone管理画面（歯車アイコン）を開く
2. プラグイン をクリック
3. プラグインの読み込み をクリック
4. kintone-doc-generator.zip を選択してアップロード
5. アップロード完了後、対象アプリの設定画面を開く
6. プラグイン タブから「ドキュメントジェネレーター」を追加
7. 設定 をクリックしてプラグイン設定画面を開く

プラグイン設定

対象アプリの設定画面で「ドキュメントジェネレーター」の 設定 をクリックすると、プラグイン設定画面が開きます。

画面上部に設定サイズメーターが表示されます。kintoneプラグインの設定は256KBが上限です。PDFのHTMLテンプレートが大きい場合はサイズに注意してください。

ドキュメント設定の追加

「＋ ドキュメント設定を追加」 ボタンをクリックして、出力設定を1件追加します。1つのアプリに複数の設定を登録できます（例: 「請求書」「納品書」「注文確認書」を同一アプリに設定）。

各設定カードのヘッダー右側には以下のボタンが表示されます。

テンプレートソース

出力形式に応じてテンプレートの指定方法が異なります。

DOCX / XLSX の場合

テンプレートファイルは別のkintoneアプリ（テンプレート保管アプリ）に添付ファイルとして登録します。

テンプレート保管アプリの準備手順:

1. 新規kintoneアプリを作成（例: 「テンプレート管理」）
2. 添付ファイルフィールドを追加（フィールドコード例: template_file）
3. テンプレートファイル（.docx または .xlsx）をレコードに添付して保存
4. レコードのURLからレコード番号を確認

プラグイン設定での指定例（請求書テンプレートの場合）:

PDF の場合

PDFのテンプレートソースは3種類から選択できます。

HTMLから作成の場合:

設定画面内のHTMLエディタに直接HTMLを記述します。フィールド一覧からタグを挿入するボタンも利用できます。エディタ右上の「全画面で編集」ボタンで全画面モーダルに拡大できます。

ページ設定:

注意: DOCX/XLSXからのPDF変換は、バックエンドの変換サービスを使用します。有効なライセンスが必要です。

出力先

生成したファイルの保存先を指定します。

同一アプリ（添付フィールド）

設定例: フィールドコード generated_docs、追記モード ON

別アプリ

クエリにはフィールドタグ（${フィールドコード}）を使用できます。クエリが空またはマッチしない場合は、出力先アプリに新規レコードを作成してファイルを保存します。

ファイル名テンプレート

生成するファイルのファイル名を指定します。フィールドタグや生成日時タグを使って動的なファイル名にできます。

請求書_${顧客名}_${作成日 format="YYYYMMDD"}
報告書_${@date format="YYYYMMDD"}

拡張子（.docx、.xlsx、.pdf）は指定不要です。プラグインが自動で付与します。

ヒント: ファイル名に使えないOS特殊文字（/、\、:、*、?、"、<、>、|）はアンダースコアに自動変換されます。

出力トリガー

ドキュメント生成のきっかけを指定します。

ボタン

レコード詳細画面にボタンを表示します。

ステータス変更

プロセス管理のステータスが変わったときに実行します。

テンプレートの準備

DOCXテンプレート

WordでDOCXファイルを作成し、差し込みたい箇所にタグを記述します。

ポイント:

• タグは ${フィールドコード} の形式
• Wordの「フィールド」機能ではなく、通常のテキストとして入力
• フォント・サイズ・色などの書式はタグに適用したものが出力に反映される
• サブテーブルのループは表（テーブル）の行に記述

作成例（請求書）:

請求書

請求先: ${顧客名}
請求日: ${請求日 format="YYYY年MM月DD日"}
お支払期限: ${期限 format="YYYY年MM月DD日"}

| 商品名 | 数量 | 単価 | 金額 |
|--------|------|------|------|
| ${#明細} ${商品名} | ${数量} | ${単価 currency="JPY"} | ${合計 currency="JPY"} ${/明細} |

合計金額: ${合計金額 currency="JPY"}

XLSXテンプレート

Excelでxlsxファイルを作成し、タグを各セルに記述します。

基本ルール:

• 1セルに1タグを記述
• セルの書式（フォント・背景色・罫線・数値書式など）はそのまま保持される

サブテーブルのループ（マーカー行方式）:

• マーカー行（${#〜} / ${/〜} のみの行）は出力に含まれません
• テンプレート行はサブテーブルの行数分だけ複製されます
• テンプレート行を複数行にすると、1サブテーブル行につき複数行を展開できます

PDFテンプレート

HTMLから作成

プラグイン設定画面のHTMLエディタでHTMLを作成します。フォント・レイアウトはCSSで調整します。

サブテーブルのループ（HTMLコメントで範囲指定）:

<table>
  <tr>
    <th>商品名</th>
    <th>数量</th>
    <th>単価</th>
  </tr>
  <!-- ${#明細} -->
  <tr>
    <td>${商品名}</td>
    <td>${数量}</td>
    <td>${単価 currency="JPY"}</td>
  </tr>
  <!-- ${/明細} -->
</table>

ヒント: 複雑なCSSレイアウト（flexbox、gridなど）はPDF変換時に再現されない場合があります。テーブルレイアウトの使用を推奨します。

DOCXから作成 / XLSXから作成

DOCXまたはXLSXのテンプレートをそれぞれのテンプレート形式で作成し、テンプレート保管アプリに添付します。生成されたDOCX/XLSXはバックエンドの変換サービスでPDFに変換されます。

テンプレートタグ仕様

オプション一覧

タグには オプション名="値" の形式でオプションを付加できます。フラグ型オプション（image・qrcode・barcode・allOptions）は値なしで記述します。

${フィールドコード オプション名="値" 別オプション="値"}
${フィールドコード image}
${フィールドコード allOptions checked="☑" unchecked="☐"}

全オプション一覧:

基本タグ

${フィールドコード}

kintoneのフィールドコードをそのまま記述します。フィールドコードはkintoneのフォーム設定で確認できます。

対応フィールド種別:

日付フォーマット

${フィールドコード format="書式文字列"}

記述例:

${作成日 format="YYYY年MM月DD日"}       → 2024年01月15日
${作成日 format="YYYY/MM/DD"}          → 2024/01/15
${更新日時 format="YYYY-MM-DD HH:mm"} → 2024-01-15 14:30

timezone オプションと組み合わせることで、任意のタイムゾーンで出力できます。

${更新日時 format="YYYY-MM-DD HH:mm" timezone="America/New_York"}

通貨フォーマット

${フィールドコード currency="通貨コード"}

${金額 currency="JPY"}     → ¥1,234,567
${amount currency="USD"}   → $1,234.56

数値フォーマット

${フィールドコード number="オプション値"}

${在庫数 number="true"}  → 1,234
${単価 number="2"}       → 1,234.00
${達成率 number="1"}     → 98.5

生成日付・日時タグ

ドキュメント生成を実行した時点の日付・日時を出力します。kintoneのフィールドではなくシステムタグです。

${@date}
${@datetime}

format オプションと timezone オプションを組み合わせられます。

${@date format="YYYY年MM月DD日"}               → 2024年01月15日
${@datetime format="MM/DD/YYYY HH:mm"}        → 01/15/2024 09:30
${@datetime format="HH:mm" timezone="Asia/Tokyo"} → 18:30

ファイル名での活用例:

請求書_${顧客名}_${@date format="YYYYMMDD"}

条件付きプレフィックス・サフィックス

${フィールドコード prefix="前置文字列"}
${フィールドコード suffix="後置文字列"}

フィールドに値がある場合のみ前後に文字を付加します。フィールドが空の場合はタグ全体が空文字になります。

使用例（住所の結合）:

${住所}${市区町村 prefix="、"}${都道府県 prefix="、"}

${備考 prefix="【" suffix="】"}

備考フィールドに値があれば 【...】 で囲んで出力、空なら何も出力しません。

改行を差し込む

オプションの値の中では \n と書くと改行になります。タグは1行に収める必要があるため、 オプションの中に実際の改行を直接書くことはできません。

${氏名 suffix="\n"}${住所}
${タグ separator="\n"}

prefix suffix のほか、配列フィールドの区切りを指定する separator でも使えます。

Excel（xlsx）での注意 セルに改行は書き込まれますが、Excel が実際に折り返して表示するのは、そのセルの書式で 「折り返して全体を表示する」が有効になっている場合のみです。テンプレート側でセルの 書式を設定してください。Word（docx）と PDF は設定不要でそのまま改行されます。

配列フィールドの出力

チェックボックス・複数選択・ユーザー選択などの配列フィールドは、デフォルトで , 区切りで出力されます。

separator — 区切り文字の指定

${チェックボックス separator=" / "}     → 選択肢A / 選択肢B / 選択肢C
${ユーザー選択 separator="・"}          → 山田太郎・鈴木花子
${複数選択 separator="\n"}              → 改行区切り

key — オブジェクト配列のプロパティ指定

ユーザー選択・組織選択・グループ選択フィールドで取得するプロパティを指定します。

${担当者 key="code" separator=","}     → user1,user2,user3

allOptions — チェックボックスの全選択肢表示

チェックボックス・複数選択フィールドの全選択肢を、選択状態（☑/☐）付きで出力します。

${チェックボックス allOptions}
→
☑ 選択肢A
☐ 選択肢B
☑ 選択肢C

${チェックボックス allOptions checked="✅" unchecked="⬜" separator=", "}
→ ✅ 選択肢A, ⬜ 選択肢B, ✅ 選択肢C

画像差し込み

kintoneの添付ファイルフィールドに添付された画像をドキュメントに埋め込みます。

${フィールドコード image}
${フィールドコード image index="1" width="300" height="200"}

フォーマット別の注意事項:

QRコード・バーコード

フィールドの値からQRコードまたはバーコードを生成して、ドキュメントに挿入します。

QRコード

${フィールドコード qrcode}
${URL qrcode width="200"}

バーコード

${商品コード barcode}
${JANコード barcode type="EAN13" width="250"}

対応バーコード形式:

条件分岐ブロック（IF/IFEXIST）

フィールドの値に応じてドキュメントの一部を表示・非表示にします。

構文

${#if フィールドコード}
表示するコンテンツ
${/if}

${#if フィールドコード = "値"}...${/if}
${#if フィールドコード != "値"}...${/if}
${#if フィールドコード > 100}...${/if}

${#if フィールドコード = "承認済み"}
承認済みです
${#else}
未承認です
${/if}

${#ifexist フィールドコード}
フィールドが存在し空でない場合に表示
${/ifexist}

3分岐以上にしたい場合（else if）

${#elseif} はありません。${#else} の中に ${#if} を入れ子にして表現します。

${#if 金額 > 10000}高額
${#else}${#if 金額 > 0}通常
${#else}なし${/if}${/if}

入れ子の数に制限はありません。${/if} は開いた ${#if} と同じ数だけ必要です。

注意: ${#elseif ...} と書いてしまうと、Word（docx）では「テンプレートエラー」で帳票の生成自体が失敗します。必ず上記の入れ子で記述してください。

条件の動作

フォーマット別の記述方法

DOCX: 段落単位でブロックを記述します。${#if ...} と ${/if} は別の段落に置きます。

XLSX: 行単位でブロックを制御します。${#if ...} と ${/if} を別の行のセルに記述します。

PDF（HTML）: HTMLコメントでブロックを囲みます。

<!-- ${#if ステータス = "承認済み"} -->
<p style="color:green">承認済み</p>
<!-- ${#else} -->
<p style="color:gray">審査中</p>
<!-- ${/if} -->

<!-- ${#ifexist 備考} -->
<p><strong>備考:</strong> ${備考}</p>
<!-- ${/ifexist} -->

注意: 条件ブロックのネストには対応していません。${#if} の中に別の ${#if} を入れることはできません。

サブテーブルのループ展開

DOCX

表の1行に開始タグ・フィールドタグ・終了タグをまとめて記述します。

| ${#明細} | ${商品名} | ${数量} | ${単価 currency="JPY"} | ${/明細} |

XLSX

マーカー行（開始・終了）とテンプレート行（データ行）を別行に分けて記述します。

PDF（HTML）

HTMLコメントでループ範囲を囲みます。

<!-- ${#明細} -->
<tr>
  <td>${商品名}</td>
  <td>${数量}</td>
  <td>${単価 currency="JPY"}</td>
</tr>
<!-- ${/明細} -->

関連レコードのループ展開

関連レコード一覧フィールドの各レコードを繰り返し出力します。サブテーブルと同じ構文を使用します。

DOCXでのネストループ

関連レコード内にサブテーブルがある場合、ネストしたループも使用できます。

${#関連案件}
  ${案件名}
  | ${#明細} | ${商品名} | ${数量} | ${/明細} |
${/関連案件}

PDF（HTML）でのネストループ

<!-- ${#関連案件} -->
<tr><td>${案件名}</td><td>${担当者}</td></tr>
  <!-- ${#明細} -->
  <tr><td colspan="2" style="padding-left:2em">${商品名}（${数量}個）</td></tr>
  <!-- ${/明細} -->
<!-- ${/関連案件} -->

注意: XLSXでは関連レコード内のサブテーブルループ（ネストループ）には対応していません。

ドキュメントの生成

ボタンで生成する場合

1. レコード詳細画面を開く
2. 設定したボタン（例: 「請求書を作成」）をクリック
3. 生成処理が実行されます（数秒〜数十秒かかる場合があります）
4. 完了後、指定した添付フィールドにファイルが保存されます

ステータス変更で生成する場合

1. レコード詳細画面でプロセス管理のステータスを変更
2. 対象ステータスへの変更時に自動でドキュメント生成が実行されます
3. 自動実行がOFFの場合: 確認ダイアログが表示されます。「OK」で生成、「キャンセル」でスキップします

一覧画面から一括生成する場合

「一覧画面で一括出力を有効にする」をONにすると、レコード一覧画面に一括出力ボタンが表示されます。

手順:

1. レコード一覧画面で絞り込み条件を設定する（任意）
2. 一括出力ボタンをクリック
3. 対象件数が確認ダイアログに表示されます。「OK」で処理を開始します
4. 処理中は進捗（一括生成中: X / Y 件）がオーバーレイ表示されます
5. 完了後に成功・失敗件数のトースト通知が表示されます

注意事項:

• 絞り込みを適用していない場合はアプリの全レコードが対象になります
• 一度に処理できる最大件数は 10,000件 です
• 処理中はページを離れないでください

ラベル印刷

これまでの「1レコード→1帳票」の生成モデルとは別の仕組みです。多数のレコード（例: 図書90冊分）を、 1枚に複数個のラベル枠を持つDOCX/XLSXシートへまとめて出力し、複数シート分は1つのZIPファイルとしてダウンロードします。

概要:

• 対象は一覧画面の絞り込み条件に一致する全レコード
• レコードを「1シートあたりの件数」ごとにグルーピングし、シートごとに1つのファイルを生成
• 生成した全シートは1つのZIPにまとめてブラウザから直接ダウンロードされます（kintoneレコードへの保存は行いません）
• 出力形式は「テンプレートと同じ形式（DOCX/XLSX）」または「PDF」から選択できます

ラベル印刷設定の追加

設定画面下部の 「＋ ラベル印刷設定を追加」 ボタンから設定を追加します。通常のドキュメント設定とは別の一覧で管理されます。

テンプレートの準備（ラベル印刷）

各ラベル枠のタグは、通常のフィールドコードの前に枠番号を付けた形式で記述します。タグ書式・枠番号の付け方はDOCX/XLSXどちらのテンプレートでも共通です。

${1_book_id}
${1_book_title}
${1_book_id barcode type="CODE128" height="25"}

${2_book_id}
${2_book_title}
${2_book_id barcode type="CODE128" height="25"}

...（テンプレートの枠数分繰り返す）...

${30_book_id}
${30_book_title}
${30_book_id barcode type="CODE128" height="25"}

なぜ番号を前置するのか: kintoneのフィールドコードは数字から始めることができません。そのため N_フィールドコード という形式は実在のフィールドコードと構造的に衝突しません。（book_id_1 のように番号を後置する形式だと、偶然同名の実フィールドが存在した場合に紛らわしくなる可能性があります。）

日付フォーマット・通貨フォーマット・バーコード・QRコードなど、テンプレートタグ仕様で説明している通常のタグオプションは、各枠のタグにそのまま使用できます（例: ${1_created_at format="YYYY/MM/DD"}）。

一覧画面からの生成（ラベル印刷）

1. レコード一覧画面で絞り込み条件を設定する
2. 設定したラベル印刷ボタン（ドキュメント名がそのままボタンラベルになります）をクリック
3. 「印刷実行時にスキップ枠数を確認する」が有効な設定の場合、スキップする枠数を入力するダイアログが表示されます（デフォルト値は設定画面の値。無効な設定ではこのダイアログは表示されません）
4. 確認ダイアログに対象レコード件数と生成されるシート数が表示されるので「OK」で実行
5. 進捗がオーバーレイ表示されます
6. 完了後、全シートを含むZIPファイルが自動的にダウンロードされます

注意事項:

• 最後のシートで対象レコード数が「1シートあたりの件数」に満たない場合、余ったラベル枠は空欄になります
• スキップ枠数を指定した場合、空欄になるのは1枚目のシートの先頭のみです。2枚目以降は通常どおり1枠目から詰められます
• 生成したファイルはkintoneのレコードには保存されません（ダウンロードのみ）
• 対象は一覧画面の絞り込み条件に一致する全レコードです。一括出力と同様、kintone REST APIの制限により一度に処理できる最大件数は 10,000件 です
• 出力形式でPDFを選択した場合はバックエンドの変換サービスを使用するため、有効なライセンスが必要です

注意事項・制限

設定サイズ制限

kintoneプラグインの設定データは 256KB が上限です。PDFのHTMLテンプレートが大きい場合は、設定画面上部のサイズメーターで確認してください。

PDF日本語フォント

html2pdf.jsはブラウザのフォントをそのまま使用します。印刷環境によっては埋め込みフォントが必要になる場合があります。

表示言語

設定画面はログインユーザーの言語設定に従って自動的に日本語または英語で表示されます。

トラブルシューティング

ドキュメントが生成されない

確認事項:

• プラグイン設定が保存されているか（設定画面で「保存」を押したか）
• テンプレート保管アプリのアプリID・レコードID・フィールドコード・ファイル名が正しいか
• 出力先の添付フィールドのフィールドコードが正しいか

フィールドの値が出力されない（タグが残る）

確認事項:

• フィールドコードが正確に一致しているか（大文字・小文字・スペースに注意）
• フィールドコードはkintoneのフォーム設定で確認できます

DOCX / XLSX でタグが変換されずそのまま出力される

確認事項:

• $ と { の間にスペースが入っていないか（$ {フィールドコード} は無効）
• Word/Excelの自動修正が ${ を変換していないか（$ と { を別々に入力してみる）
• タグ内のフィールドコードに全角スペースが混入していないか

Excelテンプレートで出力が空白になる

確認事項:

• ループのマーカー行（${#〜} / ${/〜}）が正しく対応しているか
• マーカーに使用したフィールドコードが実際のサブテーブルフィールドのコードと一致しているか

PDFのレイアウトが崩れる

確認事項:

• ページサイズと向き（縦/横）の設定が適切か
• HTMLテンプレート内のCSSで page-break-* プロパティを使って改ページ位置を制御できます
• 複雑なCSSレイアウト（flexbox、gridなど）はPDF変換時に再現されない場合があります。テーブルレイアウトの使用を推奨します

日付が正しいフォーマットで出力されない

確認事項:

• format オプションの書式文字列が正しいか（Day.js フォーマット文字列に準拠）
• フィールドの値が有効な日付形式か（kintoneの日付フィールド以外の文字列フィールドの場合、ISO形式 YYYY-MM-DD でないとフォーマットできません）