User Guide

The QB Document Generator is a cloud service that enables users to create Microsoft Word (.docx) file templates which are then populated with QuickBase data to produce .pdf, .docx, .jpeg, or .png output files.

1. Required QuickBase Tables

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

1a. Document Templates

Stores the Word template files.

Tip: Create fields in the order above and QB will assign FIDs sequentially — matching the defaults above, so no URL overrides are needed.

The No Data Message (default 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 field must be a Formula — Text field that evaluates to the DBID of your Document Subtables table. In QB, this is done with a table variable reference. Go to your Document Subtables table → Settings → Advanced to find its variable name, then enter a formula like:

[_DBID_DOCUMENT_SUBTABLES]

Replace DOCUMENT_SUBTABLES with whatever variable name QB assigned to your table. The variable name is shown in the table's Advanced Settings page.

1b. Document Subtables

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

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

2. Authoring a Template Document

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

Token Overview

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 (default FID 8; override with tpfilefid if your table differs) of the corresponding record in your Document Templates table.

3. Token Reference

3a. 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 §9).
• If the field is a file attachment or contains an image URL, the image is embedded automatically (see §8).

3b. 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).

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

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

~=barcode(f[123],qrcode,60x60)~
~=barcode(f[123],code128-b,200x80)~

3d. 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 §4).

4. Subtable Configuration

Each subtable is configured by a record in the Document Subtables table. The entire configuration lives in a single text string in the Settings field (default FID 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.

Compatibility notes: keys may appear in any order (clist does not need to be last). The legacy keys type (summary reports), bdrc, bdrs, rpt, and cpad are accepted but currently ignored. For alternating row shading use alternaterowcolor — the second color of sub= is the font color, not an even-row background.

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][VALIGN][FID]:[WIDTH_PX][:[HEADER][:HDRALIGN]][|FONT]

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

Only ALIGN, FID, and WIDTH are required — e.g. LT14:70 is a complete column.

Examples:

RNT10:50            right-aligned numeric, top-aligned, field 10, 50px wide
LT11:90|U           left text, underlined
LT12:125|I:8:Calibri    left text, italic, 8pt Calibri
R$14:115:AMOUNT|B:16:Arial   right currency, header "AMOUNT", bold 16pt Arial
CC21:30:*           centered checkbox, header "*"
R#0:30:NO           row counter column, header "NO"
CH124:200:DESCRIPTION   rich text / HTML column

Image column size formats:

Full Example

~dbid=bhkkqamev,qry={'165'.EX.[Record ID#]}AND{'655'.EX.'0'},hdr=#848484-white,alternaterowcolor=#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:

Grouping & Totals

Add groupfid=FID to group rows by a field. The generator automatically sorts by the group field (before any slist sort) and renders a full-width band above each group showing the field's value, styled with the header colors.

groupfid modifiers:

Add stlist=FID.FID to subtotal numeric columns:

• With groupfid: a bold Subtotal row appears after each group. Add the grandtotal flag to also get a grand-total row at the end of the table — the sum of all subtotals (grandtotal=TEXT customizes its label; with groupfid=FID:pb it appears on the last page).
• Without groupfid: a single bold Total row at the end of the table.

Each totaled column is summed and formatted according to its clist column type — $ columns as currency, % columns as percentage, others as plain numbers.

The label defaults to "Subtotal"/"Total" in the first column. Override with stlbl:

stlbl=1.SUB          literal text "SUB" in column 1
stlbl=1.12           the group's value of field 12 in column 1
astl=r               right-align the label

Full example:

~dbid=bhkkqamev,qry={'165'.EX.[Record ID#]},groupfid=99,stlist=787.24,slist=314,clist=LT14:70:ITEM.CT124:200:DESCRIPTION.R$787:70:PRICE.R$24:70:AMOUNT~

This groups rows by field 99 and subtotals the PRICE and AMOUNT columns per group.

Note: pagebreak (N rows per page) takes precedence over groupfid — if both are set, rows are chunked by page count and grouping only affects sort order. Use groupfid=FID:pb for one-page-per-group instead. glist/tlist are accepted as aliases for groupfid/stlist.

Multi-Page Tables

Header rows are automatically marked with Word's Repeat Header Row property — when a subtable spans multiple pages, the column headers repeat at the top of every page. No configuration needed. (This also applies to <th>/<thead> rows of embedded HTML tables.)

No-Data Message

When a subtable query returns zero rows, the document generator displays a single merged-cell row with the text from the No Data Message field (default FID 10) of the template record — column headers are not rendered. If that field is blank, the table is omitted entirely (no table, no headers, nothing).

5. 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.

6. Triggering Document Generation

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

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, uploaded to QB as a .jpg or .png.

Multi-page documents return a .zip archive containing one image per page, named sequentially:

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

The document generator detects single vs. multi-page automatically — your formula URL does not need to change. The file extension is set based on the output.

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

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 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&...")

Batch Generation (Multiple Records)

One button click can generate documents for every record matching a query. Point the formula at /batch instead of /doc_generator and replace msid with a record selection. A progress page opens, generates each document sequentially (uploading to each record's faid, stamping efpdte, etc. exactly like single generation), shows per-record results, and offers a retry for any failures. Keep the tab open while it runs.

"https://gen.baseforbusinessutilities.com/batch"
& "?clientid=my-client-id"
& "&tpdbid=TEMPLATES_TABLE_DBID" & "&tpid=TEMPLATE_RECORD_ID"
& "&msdb=" & Dbid()
& "&msqry=" & URLEncode("{'10'.EX.'Active'}")
& "&faid=OUTPUT_FIELD_ID"
& "&docfmt=pdf"
& "&fn=" & URLEncode("~7.11:-~|FEB2013")

Record selection (exactly one required, replaces msid):

If more than one selection parameter is passed, the most specific wins: msids overrides msqid, which overrides msqry.

Batch filenames: a QB formula like "&fn=" & URLEncode("Inv " & [Invoice #]) evaluates on the button's record only — every document in the batch would get the same name. For per-record names, use tokens that the generator resolves against each record:

The Record ID is appended automatically (…_9.pdf) so names stay unique; disable with fnrid=n. Tip: for complex names (functions like Right(), conditionals), create a Formula — Text field on the source table that computes the full name, then reference it with a single token: fn=~250~.

Merged PDF (optional, docfmt=pdf only): after all documents generate, one combined PDF of every successful document (in processing order) can be stored on a record of your choice:

& "&mrgdbid=" & Dbid() & "&mrgrid=" & [Record ID#] & "&mrgfa=10" & "&mrgfn=AllInvoices"

Failure handling: a failed document never stops the batch or the merge — the merged PDF is built from the successful documents only. After using Retry failed, the merge re-runs automatically with every successful document included, in the original query order (the new merged file replaces the previous one). If the merge itself fails, a Retry merge button re-attempts just the merge.

Limits: batches process 50 documents by default. Raise it deliberately with maxdocs=N — documents generate sequentially, so budget roughly 4–8 seconds each.

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 document generator 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
LI2688: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. HTML Rich Text

When a ~FID~ token's value is HTML, it is converted to Word 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 document generator detects which case applies automatically based on the HTML content.

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.

10. 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 below or above the bars:

~=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 at runtime via barcode.tec-it.com and embedded as GIF images.

11. Troubleshooting

"No file found at Document Templates record…"

The template record exists but has no .docx file attached to the MS Word Template File field. Upload a .docx to that field. If your table's file attachment field has a FID other than the default (8), specify it in the URL using tpfilefid=YOUR_FID.

"The template is a legacy .doc file…"

Templates must be in the modern .docx format — the older binary .doc format is not supported. Open the file in Word, choose File → Save As → Word Document (.docx), upload the .docx to the template record, and check the layout once in the next generated document.

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 replaces the token with an empty string — the token itself will not appear in the output.

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 Subtables DBID formula field on the template record returns the correct DBID.

Subtable text is invisible / white-on-white

The body text color of a subtable comes from the sub=BG-FONT setting's second color when present, otherwise from the font color of the ~strid=N~ token in the Word template — if that token was formatted white (easy to do accidentally on a colored background), the whole table body follows. The generator auto-corrects unreadable combinations (falling back to black or white based on the row background), so if you see this, regenerate — and check the token's font color in the template if you want a specific body color. To disable the auto-correction and render colors exactly as configured, add the nocolorguard flag to the settings string.

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. For QB-hosted images, confirm the app credentials configured for this client have read access to the source table and record.

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 the 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 or missing

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 barcode service (barcode.tec-it.com) is a public API — confirm it is reachable from your network if testing locally. It is always reachable during cloud generation.