QB Document Generator — User Guide

The QB Document Generator is a cloud service that enables users to create Microsoft Word (.docx) file templates which then can be populated with QuickBase data to create .PDF or .docx output files.

Table of Contents

1. Required QuickBase Tables
2. Authoring a Template Document
3. Triggering Document Generation
4. URL Parameter Reference
5. Token Reference
6. Subtable Configuration
7. Field Type Support
8. Images
9. Image Output (JPEG / PNG)
10. HTML Rich Text
11. Barcodes
12. Troubleshooting

1. Required QuickBase Tables

Two QB tables must be created inside the QB application. The FIDs shown below are the defaults the worker expects. If your tables were created in a different order and have different FIDs, you can override each one with a URL parameter (see §4).

1a. Document Templates

Stores the Word template files.

Tip: Create fields in the order above and the built-in QB fields (Record ID#, Date Created, etc., FIDs 1–5) will result in the worker's default FIDs being assigned automatically — no URL overrides needed.

The No Data Message (FID 10) is displayed in a subtable when the QB query returns zero rows. Leave blank to suppress the table entirely when empty.

The Subtables DBID (FID 13) must be a Formula — Text field containing exactly:

[_DBID_DOCUMENT_SUBTABLES]

This is a QB table name reference that resolves to the DBID of your Document Subtables table.

1b. Document Subtables

Stores per-template subtable configurations (one record per subtable section).

Tip: Settings should be the first user-created field so QB assigns FID 6 automatically.

1c. Your Application Table(s)

The worker reads data from whatever table you point it at (msdb). No changes required to existing tables, except:

• Add a File Attachment field to receive the generated document (faid).
• Optionally add a Date/Time field to record when the document was last generated (efpdte).

2. Authoring a Template Document

Create a standard .docx file in Word. Replace the data you want populated with tokens.

Token Overview

Tip: Word sometimes splits tokens across multiple text runs (e.g. ~12 in one run and 3~ in another). The worker automatically merges adjacent runs before substitution, so tokens will resolve correctly even if Word has split them.

Example Template Snippet

Invoice #: ~6~                    Date: ~8~
Bill To:   ~45~

~strid=1~          ← this paragraph becomes the line-items table

Notes: ~92~

Uploading the Template

Attach the .docx file to the MS Word Template File field (FID 8) of the corresponding record in your Document Templates table.

3. Triggering Document Generation

Add a Formula — URL field to your source table. When clicked, it calls the worker.

Minimal Formula (DOCX output)

"https://gen.baseforbusinessutilities.com/doc_generator"
& "?clientid=my-client-id"
& "&tpdbid=TEMPLATES_TABLE_DBID"
& "&tpid=TEMPLATE_RECORD_ID"
& "&msdb=" & Dbid()
& "&msid=" & [Record ID#]
& "&faid=OUTPUT_FIELD_ID"
& "&fn=" & URLEncode([Invoice #])
& "&docfmt=docx"

PDF Output

& "&docfmt=pdf"

Image Output (JPEG or PNG)

& "&docfmt=jpeg"
& "&docfmt=png"

Single-page documents return the image file directly. Multi-page documents return a .zip archive containing page-0001.jpg (or .png), page-0002.jpg, etc.

Append or Prepend Existing PDF Files

Use addfiles and/or prefiles to merge one or more existing QB file attachment PDFs around the generated document before it is uploaded. Works with both pdf and image output formats.

Each parameter is a dot-separated list of file references. Three reference formats are supported:

& "&prefiles=227"                          ← prepend field 227 attachment
& "&addfiles=228"                          ← append field 228 attachment
& "&addfiles=227.bu5h2c6bg:42:15"         ← field 227 + a cross-table ref

Stamp a "Last Generated" Field

& "&efpdte=DATETIME_FIELD_ID"

Stream File to Browser (in addition to QB upload)

& "&stream=y"

Fire a Pre-Generation Action

Executes a URL (fire-and-forget) before the document is built — useful for triggering a QB action or webhook:

& "&preqbaction=" & URLEncode("https://yourcompany.quickbase.com/db/TABLE?a=API_EditRecord&...")

4. URL Parameter Reference

Core Parameters

FID Override Parameters

Use these when your Document Templates or Document Subtables table has different field IDs than the defaults. All are optional — omit them if your tables use the standard field layout from §1.

5. Token Reference

5a. Field Substitution — ~FID~

Replaces the token with the value of field FID from the master record.

~168~       → value of field 168
~45~        → value of field 45

• Multiple tokens can appear on the same line or in the same paragraph.
• If the value contains HTML (e.g. a QB rich-text field), it is converted to Word formatting automatically (see §10).
• If the field is a file attachment or contains an image URL, the image is embedded automatically (see §8).

5b. Sized Image — ~I:FID:SIZE~

Embeds an image from field FID at a specific size. The token must be the only content of its paragraph (on its own line). Case-insensitive (~i:~ and ~I:~ both work).

5c. Barcode — =barcode(f[FID],type,WxH)

Generates a barcode image from the value of field FID. See §11 for full details.

=barcode(f[123],qrcode,60x60)

=barcode(f[123],code128-b,200x80)

5d. Subtable — ~strid=N~

Replaces the entire paragraph with a formatted table built from a QB query. N is the Record ID of the configuration record in the Document Subtables table.

~strid=4~

• Must be the only content of its paragraph.
• The table is rendered using the column definitions, colors, and query in the subtable config (see §6).

6. Subtable Configuration

Each subtable is configured by a record in the Document Subtables table. The entire configuration lives in a single text string in field 6.

Settings String Format

~dbid=TABLE_DBID,qry={QUERY},hdr=#COLOR-COLOR,sub=#COLOR-#COLOR,align=ALIGN,slist=FID,clist=COLUMNS~

All parts are comma-separated key=value pairs. clist must always be last because column definitions can contain commas.

Query Placeholder

Use [Record ID#] anywhere in the qry string — it is replaced with the master record's ID at runtime:

qry={'165'.EX.[Record ID#]}AND{'655'.EX.'0'}

Column Definition Format (clist)

Columns are separated by . (dot). Each column follows one of two formats:

Standard column: [ALIGN][TYPE][FID]:[WIDTH_PX]:[HEADER]

Image column: [ALIGN]I[FID]:[SIZE]:[HEADER] (no colon between I and FID)

Image column size formats:

Full Example

~dbid=bhkkqamev,qry={'165'.EX.[Record ID#]}AND{'655'.EX.'0'},hdr=#848484-white,sub=#FFFFFF-#F0F0F0,align=c,slist=314,clist=LT14:70:ITEM.CT124:200:DESCRIPTION.RF18:70:QTY.CN1245:70:UNITS.R$787:70:PRICE.R$24:70:AMOUNT~

Broken down:

No-Data Message

When a subtable query returns zero rows, the worker displays a single merged-cell row with the text from the No Data Message field (FID 10) of the template record. If that field is blank, the table is omitted entirely.

7. Field Type Support

The following QuickBase field types are handled automatically when used with ~FID~ tokens:

8. Images

8a. Master Record — Auto-Embed (~FID~)

If a field's value is a file attachment or an HTML <img> tag, the image is automatically embedded when you use a plain ~FID~ token on its own paragraph line. The image is scaled to fill the full content width.

~227~        ← if field 227 is a file attachment or <img> HTML, renders as an image

8b. Master Record — Explicit Size (~I:FID:SIZE~)

Use this token when you need precise control over image dimensions. Place it alone on its own paragraph line:

~I:227:300~          width = 300 px, height proportional
~I:227:300x200~      exactly 300 × 200 px
~I:227:50%~          50 % of original size

8c. Subtable Image Columns

Use I as the type character in a clist column definition. The worker tries the QB REST API first (file attachment fields), then falls back to extracting a URL from the field value (formula fields returning <img> HTML):

CI2688:200:PHOTO        center-aligned, FID 2688, 200 px wide, header "PHOTO"
CI2688:100x50:PHOTO     exact 100 × 50 px
LI:2688:25%:PHOTO       left-aligned, 25% of original size

8d. Subtable Auto-Image (HTML Fields)

Any subtable text column whose field value is an <img src="URL"> HTML tag will automatically render the image — no special column type needed. The image is scaled to the column width.

This is useful for formula fields that generate barcode <img> tags or reference external image URLs.

Supported Image Formats

PNG, JPEG, GIF, WebP

9. Image Output (JPEG / PNG)

When docfmt=jpeg or docfmt=png is used, the worker converts the generated document to rasterised images via Gotenberg (LibreOffice → PDF → Chromium/PDF.js render).

Single-page documents

The image file is returned directly and uploaded to QB as a .jpg or .png.

Multi-page documents

A .zip archive is returned containing one image per page, named sequentially:

page-0001.jpg
page-0002.jpg
page-0003.jpg
...

The worker detects this automatically — the QB file attachment field will receive a .zip file. Your formula URL does not need to change; the extension is set automatically based on the output.

With addfiles / prefiles

When addfiles or prefiles is used with an image format, the referenced PDFs are merged with the generated PDF before rasterisation. The final ZIP (or single image) covers all pages from all merged documents.

Requirements

Image output requires the Gotenberg secrets to be configured:

GOTENBERG_URL
GOTENBERG_CLIENT_ID
GOTENBERG_CLIENT_SECRET

10. HTML Rich Text

When a ~FID~ token's value is HTML, it is converted to Word (OOXML) formatting automatically.

Supported HTML Elements

Block vs Inline

• Block HTML (paragraphs, tables, lists): replaces the entire containing paragraph.
• Inline HTML (bold, italic, spans, line breaks): substituted within the existing run.

The worker detects which case applies automatically.

Example: QB Formula Returning a Table

A QB formula field can produce an HTML table:

<table>
  <tr><th>Tier</th><th>Price</th></tr>
  <tr><td>1–10 units</td><td>$5.00</td></tr>
  <tr><td>11–50 units</td><td>$4.50</td></tr>
</table>

When this field is referenced via ~FID~ on its own paragraph line, the entire HTML table is converted to a Word table and inserted into the document.

11. Barcodes

Use the barcode token to generate and embed a barcode image from a field value.

Token Syntax

~=barcode(f[FID],type,WxH)~

The token is case-insensitive.

Text Display Suffix (Linear Barcodes Only)

Append a suffix to type to control human-readable text:

~=barcode(f[123],code128,200x80)~       no text
~=barcode(f[123],code128-b,200x80)~     text below
~=barcode(f[123],code39-t,150x60)~      text above

Supported Symbologies

Examples

~=barcode(f[56],qrcode,80x80)~
~=barcode(f[78],ean13,200x80)~
~=barcode(f[101],code128-b,250x100)~

Barcodes are generated by barcode.tec-it.com at runtime and embedded as GIF images.

12. Troubleshooting

"No file found at Document Templates record…"

The template record exists but has no .docx file attached to FID 8 (the MS Word Template File field). Upload a .docx to that field.

Token not replaced (still shows ~168~ in output)

1. Confirm the FID is correct — check the field in QB (Admin > Fields).
2. The field may not be in the master table (msdb). Each token references a field on the master record, not related tables.
3. The field value might be empty. An empty field still replaces the token with an empty string.

Subtable is missing / not rendered

1. Confirm ~strid=N~ is on its own paragraph line in the template (no other text in that paragraph).
2. Confirm the Record ID N exists in the Document Subtables table.
3. Check the dbid in the settings string — it must match the table you're querying.
4. Confirm the formula in FID 13 of the template record returns the correct DBID.

Image shows "Picture can't be displayed"

1. Confirm the image field contains a valid file attachment or a valid <img src="URL"> value.
2. For external image URLs, confirm the URL is publicly accessible (no authentication required).
3. QB-hosted image URLs are fetched via the QB REST API using the user token — confirm the token has read access to the source table.

Currency fields show raw numbers

Currency formatting is applied automatically when the QB field type is Currency. If the field is a Formula returning a number, it will not be formatted as currency. Change the field type to Currency in QB, or use a $ type column in subtable clist (e.g. R$24:70:AMOUNT).

Date shows as a raw number (milliseconds)

The field type in QB must be Date or Date/Time. Formula fields returning a date-like number are not automatically formatted. Use a proper Date field in QB.

Barcode renders as empty

1. Confirm the field value is non-empty for the master record being generated.
2. Check that the barcode type and data are compatible (e.g. EAN-13 requires exactly 12 or 13 digits).
3. The tec-it service must be reachable from the Cloudflare Worker — it is a public API with no authentication required.