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

Umitake Document Generator for Kintone 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 screen — 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 "Umitake Document Generator for Kintone"

Plugin Configuration

Click Settings for Umitake Document Generator for Kintone 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.

Each configuration card has the following action buttons in the header:

Template Source

The method for specifying the template differs by output format.

For DOCX / XLSX

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

Preparing the template storage app:

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

Settings in the plugin configuration:

For PDF

Three template source options are available for PDF output:

Create from HTML:

Write HTML in the HTML editor on the configuration screen. Field tags can be inserted from the field list panel.

Page settings:

Create from DOCX / Create from XLSX:

Create a DOCX or XLSX template using the same format as DOCX/XLSX output, and store it in the template storage app. The configuration fields are the same as for DOCX/XLSX output (App ID, Record ID, Field Code, Filename).

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

Output Target

Specify where to save the generated file.

Same App (Attachment Field)

Example: Field code generated_docs, Append Mode ON

Another App

Field tags (${field_code}) can be used in the query. If the query matches multiple records, the file is saved to the first record found.

When the query is empty or no records match: A new record is created in the destination app and the file is saved to it. If you specify "Field to store source app ID" and "Field to store source record ID", the source app ID and record ID ($id) are automatically written to those fields when a new record is created. Using a lookup field allows you to copy related values at the same time.

Filename Template

Specify the filename for the generated document. Use field tags and system date tags to create dynamic filenames.

Invoice_${customer_name}_${invoice_date format="YYYYMMDD"}
Report_${@date format="YYYYMMDD"}

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

The ${@date} and ${@datetime} tags can be used to include the generation date or time in the filename (the format option is also supported). See System Date and Time Tags for details.

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

Output Trigger

Choose when document generation is triggered.

Button

Displays a button on the record detail screen.

Status Change

Executes 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 ${field_code}
• Enter tags as plain text, not as Word "Fields"
• Font, size, color, and other formatting applied to a tag is preserved in the output
• Subtable loops are written in table rows

Example (Invoice):

Invoice

Bill To: ${customer_name}
Invoice Date: ${invoice_date format="MMMM D, YYYY"}
Due Date: ${due_date format="MMMM D, YYYY"}

| Item | Qty | Unit Price | Amount |
|------|-----|------------|--------|
| ${#line_items} | ${item_name} | ${qty} | ${unit_price currency="USD"} | ${amount currency="USD"} | ${/line_items} |

Total: ${total_amount currency="USD"}

XLSX Template

Create an .xlsx file in Excel and write tags in individual cells.

Basic rules:

• Write one tag per cell
• Cell formatting (font, background color, borders, number format, etc.) is preserved

Subtable loop:

Loops consist of "marker rows" and "template rows" written on separate rows.

• Marker rows (rows containing only ${#...} or ${/...}) are not included in the output
• Template rows are duplicated for each row in the subtable
• Multiple template rows can be placed between markers to expand multiple output rows per subtable row
• If a marker row contains other cell content, that content is also included in the output

PDF Template

Three methods are available for PDF generation.

Create from HTML

Write HTML in the HTML editor on the plugin configuration screen.

Tips:

• Use the "Fullscreen" button (top-right of the editor) to expand to a full-screen modal
• Use CSS to control fonts and layout
• Japanese fonts use the browser's default font

Subtable loop:

Enclose the loop range with HTML comments.

<table>
  <tr>
    <th>Item</th>
    <th>Qty</th>
    <th>Unit Price</th>
  </tr>
  <!-- ${#line_items} -->
  <tr>
    <td>${item_name}</td>
    <td>${qty}</td>
    <td>${unit_price currency="USD"}</td>
  </tr>
  <!-- ${/line_items} -->
</table>

Create from DOCX

Create a DOCX template using the same tag syntax and loop format as DOCX output. The generated DOCX is converted to PDF by the backend conversion service.

→ See DOCX Template for how to prepare the template.

Create from XLSX

Create an XLSX template using the same tag syntax and loop format as XLSX output. The generated XLSX is converted to PDF by the backend conversion service.

→ See XLSX Template for how to prepare the template.

Template Tag Reference

Options Reference

Options are added to a tag in the form option_name="value". Flag-type options (image, qrcode, barcode, allOptions) are written without a value.

${field_code option_name="value" another_option="value"}
${field_code image}
${field_code allOptions checked="☑" unchecked="☐"}

All options:

Basic Tags

${field_code}

Write the kintone field code directly. Field codes can be found in your kintone form settings.

Supported field types:

Date Format

${field_code format="format_string"}

Formats date/datetime field values using the specified format string.

Examples:

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

Combine with the timezone option to output in a specific timezone:

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

Currency Format

${field_code currency="currency_code"}

Formats a numeric field value with a currency symbol.

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

Number Format

${field_code number="option"}

Formats a number with thousands separators and optional fixed decimal places (no currency symbol).

${quantity number="true"}      → 1,234
${unit_price number="2"}       → 1,234.00
${rate number="1"}             → 98.5

System Date and Time Tags

Outputs the date or time at the moment document generation is executed. These are system tags, not kintone fields.

${@date}
${@datetime}

Combine with the format and timezone options:

${@date format="MMMM D, YYYY"}                          → January 15, 2024
${@datetime format="MM/DD/YYYY HH:mm"}                  → 01/15/2024 09:30
${@date timezone="America/Chicago"}                     → 2024-01-14 (due to offset)
${@datetime format="HH:mm" timezone="Asia/Tokyo"}       → 18:30

Example for file names:

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

Conditional Prefix and Suffix

${field_code prefix="prefix_string"}
${field_code suffix="suffix_string"}

Appends text before or after a field value only when the field is not empty. If the field is null or an empty string, the entire tag outputs nothing. This is useful for joining multiple address fields without stray separators when some are empty.

Example:

${address}${city prefix=", "}${state prefix=", "}

prefix and suffix can be combined:

${notes prefix="[Note: " suffix="]"}

If notes has a value, it outputs [Note: ...]. If empty, nothing is output.

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

Check box, multi-select, user select, and similar array fields are joined with , (comma + space) by default. Use the options below to control the output format.

separator — Custom delimiter

${field_code separator="delimiter"}

${tags}                          → Design, Engineering, Sales
${tags separator=" / "}         → Design / Engineering / Sales
${assignees separator=" | "}    → Alice | Bob
${categories separator="\n"}    → line-break separated

Applicable field types: Check box, Multi-select, User select, Organization select, Group select

key — Extract a specific property from object arrays

User select, Organization select, and Group select fields are arrays of objects internally. By default, the name (display name) property is output. Use the key option to change which property is extracted.

${assignees key="code"}          → user login IDs
${assignees key="name"}          → display names (default)
${org_select key="code"}         → organization codes

Common property values:

Combine with separator as needed:

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

allOptions — Display all check box choices

Outputs all choices of a Check box or Multi-select field with checked/unchecked markers. Useful for displaying survey responses or checklists.

${field_code allOptions}
${field_code allOptions checked="☑" unchecked="☐" separator="\n"}

Option details:

Example (Check box has choices A, B, C — A and C are selected):

${checkbox allOptions}
→
☑ Choice A
☐ Choice B
☑ Choice C

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

Note: allOptions fetches the field definition (choice list) from the kintone form API. The user must have permission to read form field definitions.

Image Insertion

Embeds images from a kintone attachment field into the document.

${field_code image}
${field_code image index="0" width="200" height="150"}

Option details:

Examples:

${product_image image}                               → first image at 200×150 px
${product_image image index="1" width="300"}        → second image, 300 px wide
${employee_photo image width="100" height="120"}    → 100×120 px

Format-specific behavior:

Tip: Avoid applying character formatting (bold, color, etc.) to image tags in DOCX templates — Word may split the run internally, which prevents tag detection.

QR Code and Barcode

Generates a QR code or barcode from a field value and inserts it into the document.

QR Code

${field_code qrcode}
${field_code qrcode width="150"}

Barcode

${field_code barcode}
${field_code barcode type="CODE128" width="200" height="80"}

Supported barcode formats:

Examples:

${product_code barcode}                           → CODE128 barcode (200×80 px)
${ean_code barcode type="EAN13" width="250"}     → EAN-13 barcode (250×80 px)
${url qrcode width="200"}                         → QR code (200×200 px)

Note: If the field value is empty, no image is inserted. Some barcode formats restrict the allowed character set and length (e.g., EAN13 requires exactly 13 digits).

Conditional Blocks (IF/IFEXIST)

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

Syntax

Basic (show if field has a value):

${#if field_code}
Content shown when the field has a value
${/if}

Comparison operators:

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

Contains / does not contain (check boxes, multi-choice, etc.):

${#if field_code contains "value"}...${/if}
${#if field_code !contains "value"}...${/if}

For fields that hold multiple values (Check box, Multi-choice, User selection, …), tests whether the given value is selected. (= compares the whole value, so it never matches when several options are selected.)

${#if Favorites contains "Apple"}☑${#else}☐${/if} Apple

contains must be surrounded by spaces. On a text field it performs a substring match.

else block:

${#if field_code = "Approved"}
Document is approved
${#else}
Pending review
${/if}

IFEXIST (field existence check):

${#ifexist field_code}
Shown when the 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. You need one ${/if} per ${#if} you 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 (Word Template):

Write the block at the paragraph level. Put ${#if ...} and ${/if} on separate paragraphs (separate lines). When the condition is false, all paragraphs in the block are removed.

${#if status = "Approved"}
Approved on: ${approved_date format="MMMM D, YYYY"}
${#else}
(Pending review)
${/if}

${#ifexist notes}
Notes: ${notes}
${/ifexist}

Blocks can be nested. You need one ${/if} per ${#if} you opened.

${#if order_size contains "Minimum Order Qty"}
MOQ heading
${#if unit contains "Impressions"}
MOQ impressions line
${/if}
${#if unit contains "Feet"}
MOQ feet line
${/if}
${/if}

Showing or hiding tables:

• Whole table: Put ${#if ...} in the paragraph before the table and ${/if} in the paragraph after it. When the condition is false, the entire table is removed.
• Single row: Put ${#if ...} in the first cell of a table row and ${/if} in the last cell of the same row. When the condition is false, that row is removed (the same placement as a subtable loop).

You can also place per-row ifs inside an if block that wraps the whole table.

Note: ${#else} cannot be used in a per-row if (it causes a template error). Always put the opening and closing tags in cells of the same row.

XLSX (Excel Template):

Control blocks at the row level. Write ${#if ...} and ${/if} in cells on separate rows. When the condition is false, the rows in the block are removed.

PDF (HTML Template):

Enclose blocks with HTML comments.

<!-- ${#if status = "Approved"} -->
<p style="color:green">Approved (date: ${approved_date format="MM/DD/YYYY"})</p>
<!-- ${#else} -->
<p style="color:gray">Pending review</p>
<!-- ${/if} -->

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

Examples:

${#if total_amount >= 10000}
Free shipping applied (order over $100)
${/if}

${#if assignee = "alice"}
Assignee: Alice (ext. 1234)
${#else}
Assignee: ${assignee}
${/if}

Note: Nested conditional blocks are not supported for XLSX row-level blocks (${#if} and ${/if} on separate rows) or for PDF (HTML comment blocks). You cannot place a ${#if} block inside another block there. DOCX blocks, and ${#if} written inside a single XLSX cell, can be nested.

Subtable Loop Expansion

Repeats output for each row in a subtable field. The syntax differs by output format.

DOCX (Word Template)

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

| ${#line_items} | ${item_name} | ${qty} | ${unit_price currency="USD"} | ${/line_items} |

• ${#subtable_code} — Loop start
• ${/subtable_code} — Loop end
• The row is repeated once for each subtable row

XLSX (Excel Template)

Write marker rows (start/end) and template rows (data) on separate rows.

Marker-only rows are not included in the output. Template rows are duplicated for each subtable row.

PDF (HTML Template)

Enclose the repeating section with HTML comments.

<!-- ${#line_items} -->
<tr>
  <td>${item_name}</td>
  <td>${qty}</td>
  <td>${unit_price currency="USD"}</td>
</tr>
<!-- ${/line_items} -->

Related Records Loop Expansion

Repeats output for each record in a related records field (REFERENCE_TABLE). Uses the same syntax as subtable loops.

DOCX (Word Template)

Uses the same syntax as subtable loops.

| ${#related_projects} | ${project_name} | ${assignee} | ${/related_projects} |

If a related record contains a subtable, nested loops are supported:

${#related_projects}
  ${project_name}
  | ${#line_items} | ${item_name} | ${qty} | ${/line_items} |
${/related_projects}

XLSX (Excel Template)

Uses the same marker row / template row format as subtable loops.

Note: In XLSX, subtable fields inside related records output as empty (nested loops not supported).

PDF (HTML Template)

Enclose with HTML comments. Subtable loops inside related records can be nested.

<!-- ${#related_projects} -->
<tr>
  <td>${project_name}</td>
  <td>${assignee}</td>
</tr>
<!-- ${#line_items} -->
<tr>
  <td colspan="2" style="padding-left:2em">${item_name} (x${qty})</td>
</tr>
<!-- ${/line_items} -->
<!-- ${/related_projects} -->

Generating Documents

Using a Button Trigger

1. Open the record detail screen
2. Click the configured button (e.g., "Create Invoice")
3. Document generation runs (may take a few seconds to complete)
4. When done, 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. When Auto Execute is OFF: A confirmation dialog appears. Click "OK" to generate or "Cancel" to skip
4. When done, the file is saved to the specified attachment field

Bulk Generation from the Record List

When Enable bulk output on list view is turned ON in a Button trigger configuration, a bulk output button appears on the record list screen.

Steps:

1. Apply filter conditions on the record list screen (optional)
2. Click the bulk output button
3. A confirmation dialog shows the number of matching records — click "OK" to proceed
4. Progress is displayed as an overlay (Bulk generating: X / Y)
5. A toast notification shows the final success/failure count when complete

Notes:

• If no filter is applied, all records in the app are processed
• The maximum number of records that can be processed at once is 10,000 (kintone REST API limit)
• Do not navigate away from the page during processing
• If generation fails for some records, processing continues for the remaining records

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 have a 256 KB limit. Check the size meter at the top of the settings screen when using PDF HTML templates. Saving is blocked when the limit is exceeded.

PDF Japanese Fonts

html2pdf.js uses the browser's current fonts. Japanese text generally renders correctly, but some print environments may require embedded fonts.

Display Language

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

File Size

Generating documents from large DOCX/XLSX templates or records with many subtable rows may take longer. Keep templates as simple as possible to ensure generation completes before browser timeouts.

Troubleshooting

Document is not generated

Check:

• Plugin settings have been saved (did you click Save on the settings screen?)
• App ID, Record ID, Field Code, and Filename for the template storage app are correct
• Field code of the output attachment field is correct
• For another-app output: is the query syntax correct? (If the query is empty or no records match, a new record is created automatically)

Field value is not output (tag appears as-is)

Check:

• The field code exactly matches (watch for case sensitivity and spaces)
• Field codes can be verified in the kintone form settings

Tags are not replaced in DOCX / XLSX output

Check:

• There is no space between $ and { ($ {field_code} is invalid)
• Word/Excel auto-correct has not modified ${ (try typing $ and { separately)
• There are no full-width spaces inside the tag

Excel output is blank

Check:

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

PDF layout is broken

Check:

• Page size and orientation settings are appropriate
• Use page-break-* CSS properties in the HTML template to control page breaks
• Complex CSS layouts (flexbox, grid) may not render correctly in PDF output — table-based layout is recommended

Date is not formatted as expected

Check:

• The format string in the format option is correct (see Day.js format tokens)
• The field value is a valid date format — if you are storing dates in a plain text field rather than a kintone date field, the value must be in ISO format (YYYY-MM-DD) for formatting to work