Umitake Document Generator for Kintone — User Manual

Table of Contents

1. Overview
2. Installation
3. Plugin Configuration
   • Adding a Document Configuration
   • Template Source
   • Output Target
   • Filename Template
   • Output Trigger
4. Preparing Templates
   • DOCX Template
   • XLSX Template
   • PDF Template
5. Template Tag Reference
   • Options Reference
   • Basic Tags
   • Date Format
   • Currency Format
   • Number Format
   • System Date and Time Tags
   • Conditional Prefix and Suffix
   • Array Field Output
   • Image Insertion
   • QR Code and Barcode
   • Conditional Blocks (IF/IFEXIST)
   • Subtable Loop Expansion
   • Related Records Loop Expansion
6. Generating Documents
   • Using a Button Trigger
   • Using a Status Change Trigger
   • Bulk Generation from the Record List
7. Label Printing
   • Adding a Label Print Configuration
   • Preparing the Template (Label Printing)
   • Generating from the Record List (Label Printing)
8. Notes and Limitations
9. Troubleshooting

Overview

The Document Generator Plugin automatically generates Word (DOCX), Excel (XLSX), and PDF documents from kintone record data.

Key features:

• Insert field values into templates for document output
• Loop expansion of subtable field rows
• Loop expansion of related records fields (nested loops supported in DOCX and PDF)
• Date, currency, and number formatting
• Save generated files to an attachment field in the same app or another app
• Generate documents via button click or status change trigger
• Bulk output from the record list — process all records matching the current filter
• Label printing — pack multiple records onto DOCX label sheets (N records per sheet), downloaded as a single ZIP

Installation

1. Open the kintone admin console (gear icon)
2. Click Plugins
3. Click Import Plugin
4. Select and upload kintone-doc-generator.zip
5. After uploading, open the settings for the target app
6. From the Plugins tab, add "Document Generator"
7. Click Settings to open the plugin configuration screen

Plugin Configuration

Click Settings for Document Generator in your app's plugin settings to open the configuration screen.

A settings size meter is shown at the top of the page. kintone plugin settings have a 256 KB limit. Be careful when using large HTML templates for PDF output.

Adding a Document Configuration

Click "+ Add Document Configuration" to add one output configuration. You can register multiple configurations per app (e.g., "Invoice", "Delivery Note", "Order Confirmation" in the same app).

Each configuration card has the following buttons in the header:

Template Source

The template is specified differently depending on the output format.

DOCX / XLSX

Template files are stored as attachments in a separate kintone app (a template storage app).

Setting up the template storage app:

1. Create a new kintone app (e.g., "Template Manager")
2. Add an Attachment field (e.g., field code: template_file)
3. Attach your template file (.docx or .xlsx) to a record and save
4. Note the record number from the record URL

Plugin configuration example (invoice template):

PDF

PDF templates can be specified in three ways:

From HTML:

Write your HTML in the editor on the settings screen. Use the "Full Screen Edit" button in the editor to expand to a full-screen modal. Use the field list button to insert field tags.

Page settings:

Note: PDF conversion from DOCX/XLSX requires a valid license and uses the backend conversion service.

Output Target

Specify where the generated file should be saved.

Same App (Attachment Field)

Another App

Field tags (${fieldCode}) can be used in queries. If the query is empty or matches no records, a new record is created in the target app.

Filename Template

Specify the name of the generated file. Use field tags and system date tags for dynamic filenames.

Invoice_${CustomerName}_${InvoiceDate format="YYYYMMDD"}
Report_${@date format="YYYYMMDD"}

The file extension (.docx, .xlsx, .pdf) is added automatically — do not include it here.

Tip: OS-reserved characters (/, \, :, *, ?, ", <, >, |) in filenames are automatically replaced with underscores.

Output Trigger

Button

Displays a button on the record detail screen.

Status Change

Runs when a process management status changes.

Preparing Templates

DOCX Template

Create a DOCX file in Word and write tags where you want field values inserted.

Key points:

• Tags use the format ${fieldCode}
• Enter tags as regular text, not Word "fields"
• Font, size, color applied to the tag carry over to the output
• Subtable loops are written in table rows

Example (invoice):

Invoice

Bill To: ${CustomerName}
Invoice Date: ${InvoiceDate format="MMMM D, YYYY"}
Due Date: ${DueDate format="MMMM D, YYYY"}

| Item | Qty | Unit Price | Amount |
|------|-----|-----------|--------|
| ${#LineItems} ${ItemName} | ${Qty} | ${UnitPrice currency="USD"} | ${Amount currency="USD"} ${/LineItems} |

Total: ${TotalAmount currency="USD"}

XLSX Template

Create an XLSX file in Excel and write one tag per cell.

Basic rules:

• One tag per cell
• Cell formatting (font, background, borders, number format) is preserved in output

Subtable loop (marker row method):

• Marker rows (${#~} / ${/~} only) are not included in output
• Template rows are repeated once per subtable row
• Multiple template rows expand to multiple output rows per subtable row

PDF Template

From HTML

Write HTML in the editor on the settings screen.

Subtable loop (using HTML comments):

<table>
  <tr>
    <th>Item</th>
    <th>Qty</th>
    <th>Unit Price</th>
  </tr>
  <!-- ${#LineItems} -->
  <tr>
    <td>${ItemName}</td>
    <td>${Qty}</td>
    <td>${UnitPrice currency="USD"}</td>
  </tr>
  <!-- ${/LineItems} -->
</table>

Tip: Complex CSS layouts (flexbox, grid) may not render correctly in PDF. Table-based layouts are recommended.

From DOCX / From XLSX

Create your template using the same DOCX or XLSX format described above. The generated file is converted to PDF by the backend service.

Template Tag Reference

Options Reference

Options are appended to tags in the format optionName="value". Flag options (image, qrcode, barcode, allOptions) are written without a value.

${fieldCode optionName="value" anotherOption="value"}
${fieldCode image}
${fieldCode allOptions checked="☑" unchecked="☐"}

Full options list:

Basic Tags

${fieldCode}

Use the kintone field code exactly as shown in the form settings.

Supported field types:

Date Format

${fieldCode format="format-string"}

Examples:

${InvoiceDate format="MMMM D, YYYY"}       → January 15, 2024
${InvoiceDate format="MM/DD/YYYY"}         → 01/15/2024
${UpdatedAt format="YYYY-MM-DD HH:mm"}    → 2024-01-15 14:30

Combine with timezone to output in a specific timezone:

${UpdatedAt format="YYYY-MM-DD HH:mm" timezone="America/New_York"}

Currency Format

${fieldCode currency="currencyCode"}

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

Number Format

${fieldCode number="option"}

${Quantity number="true"}   → 1,234
${UnitPrice number="2"}     → 1,234.00
${Rate number="1"}          → 98.5

System Date and Time Tags

Output the date or time when the document was generated. These are system tags, not kintone fields.

${@date}
${@datetime}

Combine with format and timezone:

${@date format="MMMM D, YYYY"}                     → January 15, 2024
${@datetime format="MM/DD/YYYY HH:mm"}             → 01/15/2024 09:30
${@datetime format="HH:mm" timezone="Asia/Tokyo"}  → 18:30

Filename example:

Invoice_${CustomerName}_${@date format="YYYYMMDD"}

Conditional Prefix and Suffix

${fieldCode prefix="text"}
${fieldCode suffix="text"}

Prepends or appends text only when the field has a value. If the field is empty, the entire tag outputs nothing.

Example (address concatenation):

${City}${State prefix=", "}${Country prefix=", "}

${Notes prefix="[" suffix="]"}

Wraps the notes field in brackets if it has a value; outputs nothing if empty.

Inserting a line break

Write \n inside an option value to produce a line break. A tag has to stay on a single line to be parsed, so a real newline cannot be typed inside the option itself.

${name suffix="\n"}${address}
${tags separator="\n"}

Besides prefix and suffix, this also works in separator for array fields.

Note for Excel (xlsx) The line break is written into the cell, but Excel only displays it when that cell's format has Wrap Text enabled — set this in your template. Word (docx) and PDF need no extra setup.

Array Field Output

Checkbox, multi-select, and user-select fields output as arrays. Default delimiter is , .

separator — Custom delimiter

${Checkbox separator=" / "}       → Option A / Option B / Option C
${Assignees separator=" & "}      → Alice & Bob
${Tags separator="\n"}            → newline-separated

key — Property selection for user/org/group fields

${Assignees key="code" separator=","}   → user1,user2,user3

allOptions — Show all options with check marks

${CheckboxField allOptions}
→
☑ Option A
☐ Option B
☑ Option C

${CheckboxField allOptions checked="✅" unchecked="⬜" separator=", "}
→ ✅ Option A, ⬜ Option B, ✅ Option C

Image Insertion

Embed an attached image into the document.

${fieldCode image}
${fieldCode image index="1" width="300" height="200"}

Format-specific notes:

QR Code and Barcode

Generate a QR code or barcode from a field value and insert it into the document.

QR Code

${fieldCode qrcode}
${URL qrcode width="200"}

Barcode

${ProductCode barcode}
${JANCode barcode type="EAN13" width="250"}

Supported barcode formats:

Conditional Blocks (IF/IFEXIST)

Show or hide parts of the document based on field values.

Syntax

${#if fieldCode}
content to show
${/if}

${#if fieldCode = "value"}...${/if}
${#if fieldCode != "value"}...${/if}
${#if fieldCode > 100}...${/if}

${#if Status = "Approved"}
This record is approved.
${#else}
Pending approval.
${/if}

${#ifexist fieldCode}
shown when field exists and is not empty
${/ifexist}

More than two branches (else if)

There is no ${#elseif}. Nest an ${#if} inside the ${#else} instead:

${#if Amount > 10000}High
${#else}${#if Amount > 0}Normal
${#else}None${/if}${/if}

There is no limit on nesting depth — one ${/if} is required per ${#if} opened.

Warning: Writing ${#elseif ...} makes Word (DOCX) generation fail outright with a template error. Always use the nested form above.

Condition behavior

Format-specific syntax

DOCX: Write blocks at the paragraph level. Place ${#if ...} and ${/if} on separate paragraphs.

XLSX: Write blocks at the row level. Place ${#if ...} and ${/if} in separate rows.

PDF (HTML): Wrap blocks in HTML comments.

<!-- ${#if Status = "Approved"} -->
<p style="color:green">Approved</p>
<!-- ${#else} -->
<p style="color:gray">Pending</p>
<!-- ${/if} -->

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

Note: Nested conditional blocks are not supported. You cannot place a ${#if} block inside another ${#if} block.

Subtable Loop Expansion

DOCX

Write the start tag, field tags, and end tag in a single table row.

| ${#LineItems} | ${ItemName} | ${Qty} | ${UnitPrice currency="USD"} | ${/LineItems} |

XLSX

Use marker rows (start/end) and template rows (data).

PDF (HTML)

Wrap the repeating rows in HTML comments.

<!-- ${#LineItems} -->
<tr>
  <td>${ItemName}</td>
  <td>${Qty}</td>
  <td>${UnitPrice currency="USD"}</td>
</tr>
<!-- ${/LineItems} -->

Related Records Loop Expansion

Iterate over related records fields using the same syntax as subtables.

Nested loops in DOCX

${#RelatedProjects}
  ${ProjectName}
  | ${#LineItems} | ${ItemName} | ${Qty} | ${/LineItems} |
${/RelatedProjects}

Nested loops in PDF (HTML)

<!-- ${#RelatedProjects} -->
<tr><td>${ProjectName}</td><td>${Owner}</td></tr>
  <!-- ${#LineItems} -->
  <tr><td colspan="2" style="padding-left:2em">${ItemName} (${Qty})</td></tr>
  <!-- ${/LineItems} -->
<!-- ${/RelatedProjects} -->

Note: Nested loops within related records are not supported in XLSX.

Generating Documents

Using a Button Trigger

1. Open the record detail screen
2. Click the configured button (e.g., "Create Invoice")
3. The generation runs (may take a few seconds to tens of seconds)
4. On completion, the file is saved to the specified attachment field

Using a Status Change Trigger

1. Change the process management status on the record detail screen
2. Document generation runs automatically when the target status is reached
3. If Auto Execute is OFF: a confirmation dialog appears — click OK to generate or Cancel to skip

Bulk Generation from the Record List

When "Enable bulk output from list" is ON, a bulk output button appears on the record list screen.

Steps:

1. Apply filters on the record list screen (optional)
2. Click the bulk output button
3. A confirmation dialog shows the number of records to process — click OK to start
4. A progress overlay shows Bulk generating: X / Y records
5. A toast notification shows the success/failure count when complete

Notes:

• Without filters, all records in the app are processed
• Maximum records per run: 10,000 (kintone REST API limit)
• Do not navigate away from the page during processing

Label Printing

This is a separate mechanism from the usual "one record → one document" generation model. It packs a large number of records (e.g., 90 book records) onto DOCX or XLSX sheets that each have multiple label slots, producing one sheet per group of records, and bundles every generated sheet into a single ZIP for download.

Overview:

• The target is every record matching the current list view's filter
• Records are grouped into batches of "records per sheet," and one file is generated per batch
• All generated sheets are bundled into a single ZIP and downloaded directly by the browser (files are not saved to any kintone record)
• Output format can be chosen as "same format as the template" (DOCX/XLSX) or "PDF"

Adding a Label Print Configuration

Click "+ Add Label Print Configuration" at the bottom of the settings screen. Label print configurations are managed in a separate list from regular document configurations.

Preparing the Template (Label Printing)

Each label slot's tags use the field code with the slot number prefixed. The tag syntax and slot-numbering convention are identical for DOCX and XLSX templates:

${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"}

... (repeat for every slot on the template) ...

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

Why the number is prefixed: kintone field codes can never start with a digit, so the N_field_code format can never collide with a real field code. (A suffix format like book_id_1 could be confused with a genuinely different field that happens to share that name.)

Standard tag options described in Template Tag Reference — date/currency formatting, barcodes, QR codes, and so on — work the same way inside each slot's tags (e.g., ${1_created_at format="YYYY/MM/DD"}).

Generating from the Record List (Label Printing)

1. Apply filter conditions on the record list screen
2. Click the configured label print button (the document name is used as the button label)
3. If "Confirm skip count when printing" is enabled for this configuration, a dialog asks how many slots to skip (defaulting to the value from the settings screen; configurations with this disabled never show this dialog)
4. A confirmation dialog shows the number of matching records and the number of sheets that will be generated — click "OK" to proceed
5. Progress is displayed as an overlay
6. When complete, a ZIP file containing all sheets is downloaded automatically

Notes:

• If the number of matching records for the final sheet is less than "records per sheet," the remaining slots on that sheet are left blank
• When a skip count is specified, only the first sheet's leading slots are left blank. Later sheets fill normally starting from slot 1
• Generated files are not saved to any kintone record — the ZIP is downloaded only
• The target is every record matching the current list view's filter. As with bulk output, the kintone REST API limits processing to a maximum of 10,000 records at once
• Selecting PDF as the output format uses the backend conversion service and requires a valid license

Notes and Limitations

Settings Size Limit

kintone plugin settings are limited to 256 KB. Check the size meter at the top of the settings screen, especially when using large HTML templates for PDF output.

PDF Japanese Fonts

html2pdf.js uses the browser's fonts. For print environments that require embedded fonts, consider using DOCX-to-PDF conversion instead.

Display Language

The settings screen automatically displays in Japanese or English based on the logged-in user's language setting.

Troubleshooting

Document is not generated

Check:

• Plugin settings are saved (did you click Save?)
• Template storage app ID, record ID, field code, and filename are correct
• The attachment field code in the output target is correct

Field value is not inserted (tag appears in output)

Check:

• Field code exactly matches the kintone form settings (case-sensitive, no extra spaces)
• View field codes in the app's form settings

Tags not converted in DOCX / XLSX (appear as-is)

Check:

• No space between $ and { ($ {fieldCode} is invalid)
• Word/Excel autocorrect has not modified ${ (try typing $ and { separately)
• No full-width spaces inside the tag

Excel template outputs blank rows

Check:

• Loop marker rows (${#~} / ${/~}) are properly paired
• The field code in the markers matches the actual subtable field code

PDF layout is broken

Check:

• Page size and orientation settings are correct
• Use page-break-* CSS properties to control page breaks in HTML templates
• Complex CSS layouts (flexbox, grid) may not render correctly — use table-based layouts instead

Date is not formatted correctly

Check:

• The format option string is valid (follows Day.js format tokens)
• For non-date fields, the value must be in ISO format (YYYY-MM-DD) for formatting to work