Formula URL parameters—what's behind the button?
A formula field on the table that holds your master records runs XL Docs. The formula builds a URL made of a base address followed by parameters that tell XL Docs which record to read, which template to fill, what kind of file to create, and where to put it. The same parameters are used by the API and by batch processing. The installation wizard (XL Docs setup type) creates working buttons for you; this article explains every parameter so you can change them or build your own. Most parameters take a field ID or a table ID; see Find your Client ID, table IDs, and field IDs.
Base addresses
Base address | What the user sees | Use it when |
|---|---|---|
https://.../ExcelGen_LP.aspx? | A progress window. The window title is Excel Document Merge and the heading is XL Docs. While the document is created, it shows Processing... and an animated progress bar. When it's done, a green line such as 1 Document(s) generated and uploaded successfully. or a red error message appears, with a Close button. | You want to save the document to Quickbase or cloud storage and show the user a result. This address never sends the file back to the browser, so stream is ignored. |
https://.../ExcelGen_UA.aspx? | No progress window. With stream=y, the finished document comes straight back to the browser: a PDF opens in the browser, and Excel and CSV files download. If something goes wrong, an error page appears with the heading XL Docs, the bold text Something Went Wrong, the message and a Close button. | You want the user to see or download the document right away (the Stream to Browser experience). You can also save a copy to Quickbase in the same click. |
Replace https://... with your designated XL Docs server URL, created by the installation wizard. Keep the rest of the address unchanged.
How parameters are written
Separators—in a button formula, parameters are joined with & (for example clientid=Q#&appid=...). In batch arguments, they are separated by spaces and there is no base address. See Batch processing.
Names are not case-sensitive—amazonS3=Y and amazons3=y mean the same thing. Values such as file names keep their case. Write docfmt values in lowercase (pdf, csv, xlsx).
Yes/no values—use y or n. Upper or lower case both work.
Field values—wrap text that comes from a field in URLEncode() so special characters reach XL Docs intact, for example URLEncode([Client Name]).
Unknown names are ignored—a misspelled parameter name doesn't cause an error; it just has no effect. If a setting doesn't seem to apply, check the spelling first.
Encoded request—instead of listing the parameters, you can Base64-encode the whole parameter string and send it as a single parameter: request=<Base64 string>. When request is present, every other parameter in the URL is ignored. Values inside the encoded string are not URL-decoded, so don't URL-encode them first.
Required parameters
Every request needs clientid, appid, dbid, tpdbid, tpid, fn, and exactly one of msid (one record) or msqry (many records). If one is missing, or both msid and msqry are supplied, no document is created and the user sees A required parameter is missing or malformed. Please double-check your request, or contact your Quickbase support representative if the issue persists. See XL Docs messages and troubleshooting.
Parameter reference
The following table lists every parameter, grouped by purpose. Unless a row says otherwise, a parameter works the same in buttons, the API, and batch processing.
Parameter | Description | Sample in formula |
|---|---|---|
Authorization parameters—identify the account and application running XL Docs. | ||
clientid | Required. Your Quickbase Extensions Client ID: Q followed by a number, assigned to your account. The installation wizard writes it into every button it creates. See Find your Client ID, table IDs, and field IDs. | "clientid=Q#" |
appid | Required. The ID of the Quickbase application. Used to confirm the application is authorized to use XL Docs. | "&appid=" & AppID() |
apptoken | Optional. If your application requires application tokens, pass a token here. XL Docs uses it when it reads your records and saves documents. Leave it blank (or leave it out) if your app doesn't require tokens. | "&apptoken=[Your App Token]" |
Record and template parameters—which record to read and which template to fill. See Build a document template and Document Templates table reference. | ||
dbid | Required. The ID of the master table—the table that holds the record(s) the document is built from. The faid file attachment field is on this table. Use the built-in function Dbid() when the button is on the master table, or a table alias such as [_DBID_PROJECT_EMPLOYEES] when the button creates documents for a related table. With the enhanced security button, data-temptokendbid must name the same table as dbid (for example Dbid() for both, or [_DBID_PROJECT_EMPLOYEES] for both), because XL Docs checks the temporary token against that table. See Find your Client ID, table IDs, and field IDs. | "&dbid=" & Dbid() |
msid | Required unless you use msqry. The Record ID# of the master record to process. Creates one document. Typically the built-in key field; if it has been renamed, use the renamed field label between the brackets. | "&msid=" & [Record ID#] |
tpdbid | Required. The ID of the Document Templates table—the table in your app that stores your templates. Use the table alias (for example [_DBID_DOCUMENT_TEMPLATES]) instead of typing the table ID. | "&tpdbid=" & [_DBID_DOCUMENT_TEMPLATES] |
tpid | Required. The Record ID# (a number) of the template record in the Document Templates table to use. | "&tpid=1" |
Output and file name parameters—the name and format of the document and how it's delivered. See Output and storage. | ||
fn | Required. The file name for the document, without an extension—XL Docs adds the extension for the format. Single record: XL Docs adds an underscore and the Record ID# to the name, so fn=PurchaseOrder on record 3 gives PurchaseOrder_3.xlsx (or PurchaseOrder_3.pdf). Use fnrid=N to leave the number off. Multiple records: to name each document from its own record, put field IDs between tildes, separated by periods: fn=~7.11~ joins the values of fields 7 and 11 with a hyphen. If field 7 is Quickbase and field 11 is 1007, the file is Quickbase-1007.xlsx (or Quickbase-1007.pdf). The characters \ / : * < > | ? " and periods are removed from the name (not replaced). Wrap field values in URLEncode(). | "&fn=PurchaseOrder" "&fn=PO_" & URLEncode([PO Number]) "&fn=~7.11~" |
fnrid | Optional. File name Record ID#. By default the Record ID# is added to the end of the file name (Invoice_123.pdf). Set to N to leave it off (Invoice.pdf). | "&fnrid=N" |
docfmt | Optional. The output format. Use lowercase. pdf—a PDF file. All worksheets are included unless the template record's PDF Pages field lists specific sheets. All columns fit on one page width. csv—a comma-separated values file. Formulas don't transfer to a CSV—only their values do. xlsx, or leave it out—an Excel workbook in the same file type as the template (.xlsx, .xls, or .xlsm). XL Docs doesn't convert between Excel file types: an .xlsx template always produces an .xlsx workbook. | "&docfmt=pdf" "&docfmt=csv" "&docfmt=xlsx" |
docpw | Optional. Password-protects the document. For a PDF or an Excel workbook, the password is needed to open the file. Has no effect on CSV files. | "&docpw=ab123" |
stream | Optional. y sends the document back to the browser when it's created—a PDF opens in the browser; an Excel or CSV file downloads to the browser's download tray (and may open in your local Excel). Works only with the ExcelGen_UA.aspx address; ExcelGen_LP.aspx ignores it. With msqry, the document streams only when sameworkbook=y. Default is n (don't stream). You can stream and save in the same click—add a storage parameter such as faid. | "&stream=y" |
noutf8bom | Optional. CSV only. Set to y to write the CSV without the UTF-8 byte order mark (BOM). Most programs don't mind the BOM, but some importers (for example SAP Ariba) need the file written without it. | "&noutf8bom=y" |
Storage: file attachment field—save the document on the record it was created for. | ||
faid | Optional. The field ID of the file attachment field on the master record (in dbid) that receives the document. Must be a number. With msqry, each document is saved on its own record. See Find your Client ID, table IDs, and field IDs. | "&faid=51" |
xlddte | Optional. XL Docs Date. The field ID of a Date/Time field on the master record that's updated with the date and time XL Docs created the document. | "&xlddte=92" |
Storage: repository table—also save the document in a separate table that holds all generated documents. A repository table can't be used with Dropbox. See Output and storage. | ||
repository | Set to y to save the document in a repository table, in addition to any other storage you specify. | "&repository=y" |
rpdbid | The ID of the repository table. | "&rpdbid=" & [_DBID_DOCUMENTS] |
rpfid | The field ID in the repository table that relates it to the master table—for example, the [Related PO] field if the repository is related to a Purchase Orders table. It's set to the master record's Record ID#, or to rpfidval if you supply one. | "&rpfid=9" |
rpfidval | Optional. The value to put in rpfid instead of the master record's Record ID#. Use it when the relationship uses a key field other than Record ID# (field 3). | "&rpfidval=" & URLEncode([PO Number]) |
rpfafid | The field ID of the file attachment field in the repository table that receives the document. | "&rpfafid=13" |
rpmode | Optional. a (add) always creates a new repository record. u (update) updates an existing record: XL Docs looks for records whose rpfid matches (and, if you supply them, whose rpkfid field equals rpkval). If none is found, a new record is added. If more than one is found, only the most recent one is updated. If you leave rpmode out, update mode is used. | "&rpmode=a" "&rpmode=u" |
rpkfid | Optional, update mode. The field ID in the repository table to search to find the record to update. | "&rpkfid=20" |
rpkval | Optional, update mode. The value to look for in rpkfid. | "&rpkval=" & URLEncode([Document Type]) |
rpmap | Optional. Copies field values from the master record onto the repository record. Write pairs of repository field ID:master field ID, separated by |. Pairs must be field IDs—fixed values aren't accepted. | "&rpmap=9:6" "&rpmap=9:6|6:220|7:218" |
Storage: Amazon S3—save the document to your Amazon S3 bucket. Your S3 credentials are saved during setup; see Amazon S3 setup. | ||
amazons3 | Set to y to save the document to Amazon S3. | "&amazons3=y" |
s3bkt | Optional. The bucket to save to. A default bucket is set up for your account; this overrides it. | "&s3bkt=my-bucket" |
s3key | Optional. Overrides the Amazon S3 secret key saved for your account. Use it only if you rotate keys yourself and need to pass the current one; store it in an app variable rather than typing it into the formula, because anything in the URL is visible to people who can see the button's formula. | "&s3key=" & [S3 Secret Key] |
s3keyval | Optional. The S3 object key (path and name) to save the document under. Use {xl_filename} for the document's file name, or {xl_filename_dbid} for the default key. Leading and trailing / are removed. If you leave it out, the key is built from the document's file name. | "&s3keyval=" & URLEncode("invoices/{xl_filename}") |
keyfid | Optional. The field ID of a text field that receives the S3 key, which links the document to the record in Quickbase. When you save to a repository table and S3 together, this is the S3 key field in the repository table. | "&keyfid=81" |
psu | Download links only. With y, an S3 download link opens the file through a pre-signed URL. See Output and storage. | "&psu=y" |
Storage: Dropbox—save the document to Dropbox. A repository table can't be used with Dropbox. See Dropbox setup. | ||
dropbox | Set to y to save the document to Dropbox. | "&dropbox=y" |
dropboxdir | Optional. The Dropbox folder to save to, as a full path from the top of your Dropbox. If you leave it out, the default folder set up for your account is used. A file with the same name in that folder is overwritten. | "&dropboxdir=/Invoices/2026" |
dropboxkeyfid | Optional. The field ID of a field that holds the key linking the document to the record in Quickbase. dropboxfile is accepted as an alternative name. | "&dropboxkeyfid=81" |
Merging PDFs—combine the generated PDF with other PDF files, or combine the PDFs for many records into one file. All of these need docfmt=pdf. See Output and storage. | ||
prefiles | Optional. PDF files to put before the generated PDF. A period-separated list; each item can be: a file attachment field ID on the current record (15); dbid:recid:faid for a file on another record (bxxxxxxxx:7:12); S3|<object key> for a file in your S3 bucket; RID, which is replaced by the current Record ID# (for example in bxxxxxxxx:RID:12); or FID followed by a field ID (FID523), which is replaced by that field's value on the master record. | "&prefiles=15" |
addfiles | Optional. PDF files to put after the generated PDF. Same format as prefiles. Together, prefiles and addfiles can list up to 10 files by default; your account's limit may differ. If you list more, no document is created and you see You cannot merge more than <N> addfiles/prefiles file(s). Please open a Quickbase support ticket for further information. Without docfmt=pdf, you see The 'addfiles'/'prefiles' parameters are only supported when 'docfmt' is 'pdf'. If a listed field is empty on the record, it's skipped. | "&addfiles=15.16" "&addfiles=" & [_DBID_TERMS] & ":1:6" |
mrgdbid | With msqry: merge every record's PDF into one PDF. The ID of the table to save the merged PDF in. Use together with mrgrid and mrgfa. Without docfmt=pdf, no document is created and you see The 'mrgdbid'/'mrgfa'/'mrgrid' parameters are only supported when 'docfmt' is 'pdf'. | "&mrgdbid=" & Dbid() |
mrgrid | The Record ID# of the record to save the merged PDF on. | "&mrgrid=" & [Record ID#] |
mrgfa | The field ID of the file attachment field that receives the merged PDF. | "&mrgfa=242" |
mrgfn | Optional. The name of the merged PDF. .pdf is added, or replaces any other extension. Default: Merged_XL_Docs_File.pdf. | "&mrgfn=ALL_Project_Expense_Sheets" |
mrgdte | Optional. The field ID of a Date/Time field on the mrgrid record that's set to the date and time the merged PDF was created. | "&mrgdte=243" |
Multiple records—create documents for many records in one click. See Generate documents for multiple records. | ||
msqry | Use instead of msid. A Quickbase query on the master table (dbid); XL Docs creates a document for each matching record. The sample creates a document for every record whose field 10 is Active. Instead of a query, you can give a report ID (a number)—documents are created for every record in that report. Records are processed in the table's default sort order. To choose which records run, use a report or a query. Buttons and the API create up to 50 documents per request by default; your account's limit may differ. For more, use batch processing. | "&msqry={'10'.EX.'Active'}" "&msqry={'6'.EX.'" & [Record ID#] & "'}" "&msqry=5" |
msqid | A report ID. The installation wizard uses it for batch setups that select records with a report. If you supply msqid and neither msid nor msqry, it's treated as msqry with that report ID. | "&msqid=1" |
sameworkbook | Optional, with msqry. Set to y to put every record in one workbook, one worksheet (tab) per record, instead of one document per record. | "&sameworkbook=y" |
snfid | Optional, with sameworkbook. The field ID whose value names each tab. Only letters, numbers, spaces, and - | + @ # $ & ( ) _ , . ! ^ are kept. Without it, tabs are named from the template tab with a number (<tab>_1, <tab>_2, ...). | "&snfid=6" |
swbdbid | Optional, with sameworkbook. The ID of the table to save the workbook in. Use together with swbrid and swbfaid—all three are needed. | "&swbdbid=" & Dbid() |
swbrid | The Record ID# of the record to save the workbook on. | "&swbrid=" & [Record ID#] |
swbfaid | The field ID of the file attachment field that receives the workbook. | "&swbfaid=155" |
Pre-actions—update the record before the document is created. See Run a Quickbase API call before generating below. | ||
preqbaction | Optional, buttons only. A Quickbase API call to run on the record before the document is created, wrapped in Base64Encode(). If the call fails, no document is created and the user sees the Quickbase error. Requires the enhanced security button (POSTTempToken). Not run by the API or batch processing. | "&preqbaction=" & Base64Encode(URLRoot() & "db/" & Dbid() & "?a=API_EditRecord&rid=" & [Record ID#] & "&_fid_50=Started") |
Batch processing parameters—used in the batch arguments field. Separate them with spaces, not &. See Batch processing. | ||
type | Batch only. Which batch processor runs the arguments. xldocsbatch, or xldocsbatcheu for accounts hosted in the EU. The installation wizard sets the right value for your account. | " type=xldocsbatch" |
xldbdbid | The ID of the table the batch run is started from (for example the XL Docs Batch Processing table). | " xldbdbid=" & Dbid() |
xldbrid | The Record ID# of the record the batch run is started from. | " xldbrid=" & [Record ID#] |
xldbtfld | The field ID of the text field on that record that shows the run's status. It's set when the run is requested, then updated when the run finishes: PROCESS COMPLETED_<date and time>, or the error message if something went wrong. To get a status message back in your app, supply all three of xldbdbid, xldbrid, and xldbtfld. | " xldbtfld=7" |
triggerfid | Optional, batch only, single-record runs (dbid with msid). The field ID of a text field on the record being processed that shows the run's status. When the run starts, XL Docs writes PROCESSING_<date and time>. When it finishes, it writes PROCESS COMPLETED_<date and time>, or the error message if something went wrong. For multi-record runs, use xldbtfld instead. If the status can't be written, the document is still created. The installation wizard doesn't add this parameter; to see the status in the XL Docs Batch Trigger Field, add triggerfid with that field's ID to the XL Docs Batch Processing Arguments formula. | " triggerfid=8" |
logsdbid | Optional. The ID of a log table (for example the XL Docs Batch Processing Logs table) that gets a record for every run, with its start and end time, status (Completed or Error), notes, and the number of documents processed. | " logsdbid=" & [_DBID_XL_DOCS_BATCH_PROCESSING_LOGS] |
configid | Batch only. The Config Key of the batch configuration the installation wizard created for these arguments. Every batch run is checked against that configuration, so don't change it. See Batch configurations. | " configid=..." |
Advanced parameters | ||
parse | Optional. Set to y when the template is complex and processing hangs—for example, a template with broken links or pivot table problems. XL Docs then opens the template so each worksheet is parsed only when it's needed. | "&parse=y" |
insertsf | Optional. Preserves special formatting, such as merged cells, when a data table uses Max Line items with Max Lines type = Insert New Rows. XL Docs copies the format of the row already defined where the new rows are inserted. See Tips and examples. | "&insertsf=y" |
datachunk | No longer needed. Large data sets are always retrieved in chunks, so you can leave it out. | Not needed |
request | Optional. The whole parameter string, Base64-encoded. When it's present, all other parameters in the URL are ignored. See How parameters are written above. | "?request=" & Base64Encode("clientid=Q#&appid=" & AppID() & "...") |
Examples
These buttons use the enhanced security pattern: a Formula - Text field with Allow some HTML tags turned on, whose link has the classes OpenAsPopup POSTTempToken and a data-temptokendbid attribute. Quickbase then sends a temporary token with the request so XL Docs can confirm the user has access to the record. XL Docs checks the token against the table in dbid, so data-temptokendbid must name the same table as dbid: Dbid() when dbid is Dbid(), or the same table alias, such as [_DBID_PROJECT_EMPLOYEES], when the button creates documents for a related table. See Change formula fields and Configure pop-ups.
Save an Excel workbook to the record (progress window)
Creates an Excel workbook from template record 1, names it PO_ plus the PO number (with the Record ID# added), saves it in file attachment field 51, and sets Date/Time field 92 to the date and time it was created. The user sees the progress window, then 1 Document(s) generated and uploaded successfully.
var text url = "https://.../ExcelGen_LP.aspx?" // your XL Docs server URL, created by the installation wizard
& "clientid=Q#" // your Client ID
& "&appid=" & AppID()
& "&dbid=" & Dbid()
& "&msid=" & [Record ID#]
& "&tpdbid=" & [_DBID_DOCUMENT_TEMPLATES]
& "&tpid=1"
& "&fn=PO_" & URLEncode([PO Number])
& "&docfmt=xlsx"
& "&faid=51"
& "&xlddte=92"
& "&apptoken=[Your App Token]"; // only if your app requires application tokens
"<a class='Vibrant Success OpenAsPopup POSTTempToken' data-height=400 data-width=800 data-refresh=true data-temptokendbid='" & Dbid() & "' href=\"" & $url & "\">Create Purchase Order</a>"Open a PDF in the browser and keep a copy
Uses the ExcelGen_UA.aspx address with stream=y, so the PDF opens in the pop-up as soon as it's created. A copy is also saved in field 51, so the user can close the window without losing the document.
var text url = "https://.../ExcelGen_UA.aspx?" // your XL Docs server URL, created by the installation wizard
& "clientid=Q#" // your Client ID
& "&appid=" & AppID()
& "&dbid=" & Dbid()
& "&msid=" & [Record ID#]
& "&tpdbid=" & [_DBID_DOCUMENT_TEMPLATES]
& "&tpid=2"
& "&fn=Invoice_" & URLEncode([Invoice Number])
& "&fnrid=N"
& "&docfmt=pdf"
& "&stream=y"
& "&faid=51"
& "&xlddte=92";
"<a class='Vibrant Success OpenAsPopup POSTTempToken' data-height=1000 data-width=1000 data-refresh=true data-temptokendbid='" & Dbid() & "' href=\"" & $url & "\">View Invoice PDF</a>"Save a PDF to Amazon S3
Saves the PDF to your account's S3 bucket under invoices/, writes the S3 key to field 81 so the record links to the file, and sets field 92 to the date and time.
var text url = "https://.../ExcelGen_LP.aspx?" // your XL Docs server URL, created by the installation wizard
& "clientid=Q#" // your Client ID
& "&appid=" & AppID()
& "&dbid=" & Dbid()
& "&msid=" & [Record ID#]
& "&tpdbid=" & [_DBID_DOCUMENT_TEMPLATES]
& "&tpid=2"
& "&fn=Invoice_" & URLEncode([Invoice Number])
& "&docfmt=pdf"
& "&amazons3=y"
& "&s3keyval=" & URLEncode("invoices/{xl_filename}")
& "&keyfid=81"
& "&xlddte=92";
"<a class='Vibrant Success OpenAsPopup POSTTempToken' data-height=400 data-width=800 data-refresh=true data-temptokendbid='" & Dbid() & "' href=\"" & $url & "\">Save Invoice to S3</a>"Run a Quickbase API call before generating
Use preqbaction to update the record as part of the same click—for example, to set a status field before the document is created. This replaces the older pattern of a button that runs an API call and then redirects to XL Docs, which doesn't work with Quickbase enhanced security.
Write the API call as a URL to your own realm, built with URLRoot(), for example URLRoot() & "db/" & Dbid() & "?a=API_EditRecord&rid=" & [Record ID#] & "&_fid_50=Started". Don't include an rdr= part.
Wrap it in Base64Encode()—a built-in Quickbase formula function—and pass it as the parameter: & "&preqbaction=" & Base64Encode( ... ).
Use the enhanced security button (POSTTempToken and data-temptokendbid, as in the examples above). The call runs with the clicking user's permissions. Without the temporary token, the call isn't run.
var text url = "https://.../ExcelGen_LP.aspx?" // your XL Docs server URL, created by the installation wizard
& "clientid=Q#" // your Client ID
& "&appid=" & AppID()
& "&dbid=" & Dbid()
& "&msid=" & [Record ID#]
& "&tpdbid=" & [_DBID_DOCUMENT_TEMPLATES]
& "&tpid=1"
& "&fn=Quote"
& "&docfmt=pdf"
& "&faid=51"
& "&preqbaction=" & Base64Encode(URLRoot() & "db/" & Dbid() & "?a=API_EditRecord"
& "&rid=" & [Record ID#] & "&_fid_50=Quote sent");
"<a class='Vibrant Success OpenAsPopup POSTTempToken' data-height=400 data-width=800 data-refresh=true data-temptokendbid='" & Dbid() & "' href=\"" & $url & "\">Create Quote</a>"The call must point at your own Quickbase realm. Any other address is rejected with Direct Call's URL is invalid.
If the call fails, no document is created and the error appears in the progress window or on the error page.
preqbaction isn't run by the API or by batch processing.
We understand these parameters can be complex—submit a technical support case if you have any questions.