Output and storage

Every XL Docs request decides three things about the finished document: its format, its name, and where it goes. This article explains each choice and the parameters that control it. For the full parameter list, see Formula URL parameters.

Output formats

Set the format with docfmt. Write the value in lowercase. The installation wizard's Output File Type option (XLSX, PDF, or CSV) sets the same thing.

Password protection

Add docpw to require a password to open the document. It works for PDF and Excel output and has no effect on CSV files. Use a field value to give each document its own password:

& "&docpw=" & URLEncode([Document Password])

Opening a downloaded workbook may show Excel's own Protected View banner with an Enable Editing button. That banner comes from Excel, not from XL Docs—see Tips and examples.

File names

fn is required and sets the file name without an extension; XL Docs adds .xlsx, .xls, .xlsm, .pdf, or .csv to match the format.

• The characters \ / : * < > | ? " and periods are removed from the name, not replaced.

• Wrap text from fields in URLEncode() so characters such as & and # reach XL Docs intact.

• When you save to Dropbox or to a fixed S3 key, a new document with the same name replaces the old one.

Stream or save

The base address in the formula decides whether the user gets the document back in the browser:

• Stream and save together—add a storage parameter such as faid to a streaming button. The document is saved first and then sent to the browser.

• A streamed PDF is shown once. The PDF is removed from the server after it's displayed; if the browser asks for it again within a few minutes it gets nothing. Save a copy (for example with faid) if users need to come back to it.

• Multiple records—with msqry, nothing is streamed unless sameworkbook=y puts every record in one workbook. Each record's document is saved instead.

• Not streaming? Use the ExcelGen_LP.aspx address so the user sees a result. With ExcelGen_UA.aspx and no stream=y, the document is saved but nothing is shown.

Where documents are saved

You can use one storage option or combine several in the same request—for example, save to the record's file attachment field and to Amazon S3. The one combination that isn't supported is a repository table with Dropbox: a repository table can't be used with Dropbox.

The storage parameters take field IDs and table IDs from your app. To look them up, see Find your Client ID, table IDs, and field IDs.

File attachment field on the record

faid is the field ID of a file attachment field on the master record (the table in dbid). xlddte is a Date/Time field on the same record that's set to the date and time the document was created. With msqry, each record's document is saved on that record.

& "&faid=51"
& "&xlddte=92"

Repository table

A repository table is a separate table in your app that holds all the documents you create—one place for every file, instead of a file attachment field on each record. Each document becomes (or updates) a record in that table, related back to the master record. See also Repository table step in the installation wizard. A repository table can't be used with Dropbox; to keep documents in a repository table, save them to the table's file attachment field or to Amazon S3.

1. Set repository=y and rpdbid to the repository table.

2. Set rpfafid to the file attachment field in the repository table that receives the document.

3. Set rpfid to the field in the repository table that relates it to the master table (for example [Related PO]). XL Docs puts the master record's Record ID# there—or rpfidval, if the relationship uses a different key field.

4. Choose a mode with rpmode: a always adds a new repository record, so you keep every version; u updates the existing record for this master record (matched on rpfid, plus rpkfid = rpkval if you supply them). In update mode, a new record is added if none matches, and only the most recent one is updated if several match. Update mode is used if you leave rpmode out.

5. Optionally copy fields from the master record onto the repository record with rpmap, as repository field ID:master field ID pairs separated by |.

This example keeps one repository record per purchase order and document type, replacing the file each time:

& "&repository=y"
& "&rpdbid=" & [_DBID_DOCUMENTS]
& "&rpfid=9"          // [Related PO] in the repository table
& "&rpfafid=13"       // file attachment field in the repository table
& "&rpmode=u"
& "&rpkfid=20"        // [Document Type] in the repository table
& "&rpkval=Purchase Order"
& "&rpmap=6:7|8:12"   // copy master fields 7 and 12 into repository fields 6 and 8

When you save to a repository table and Amazon S3 together, set keyfid to the S3 key field in the repository table.

Amazon S3

Set amazons3=y to save the document to your Amazon S3 bucket. Your access key, secret key, and default bucket are saved for your account during setup—see Amazon S3 setup. If no S3 credentials are saved for your account, the request stops with Cloud storage upload could not be configured for this request. Please contact support.

• s3bkt—save to a different bucket than your default.

• s3keyval—the object key (folder path and name). {xl_filename} is replaced by the document's file name and {xl_filename_dbid} by the default key. Leading and trailing / are removed. Without it, the key is built from the document's file name.

• keyfid—a text field that receives the S3 key, so the record knows where its file is. Use it to build download links (below) or to show the key on a form.

• s3key—overrides the saved secret key, for accounts that rotate keys themselves. Keep the value in an app variable rather than in the formula.

& "&docfmt=pdf"
& "&amazons3=y"
& "&s3keyval=" & URLEncode("projects/" & [Project Number] & "/{xl_filename}")
& "&keyfid=81"

Dropbox

Set dropbox=y to save the document to Dropbox. Your Dropbox connection is set up for your account—see Dropbox setup. Dropbox can't be used with a repository table.

• dropboxdir—the folder to save to, as a full path from the top of your Dropbox (for example /Invoices/2026). Without it, the default folder set up for your account is used. A file with the same name in that folder is overwritten.

• dropboxkeyfid (or dropboxfile)—a field that holds the key linking the document to the record.

& "&dropbox=y"
& "&dropboxdir=" & URLEncode("/Exports/" & [Customer Name])

Download links for files in cloud storage

Documents saved to Amazon S3 or Dropbox aren't in a Quickbase file attachment field, so give users a link to download them. A download link points to the Download.aspx address on your XL Docs server, which delivers the file to the user through a secure download link.

var text url = "https://.../Download.aspx?"  // your XL Docs server URL, created by the installation wizard
& "clientid=Q#"  // your Client ID
& "&appid=" & AppID()
& "&dbid=" & Dbid()
& "&msid=" & [Record ID#]
& "&psu=y"
& "&fn=" & URLEncode([S3 Key]);

"<a class='Vibrant Success' href=\"" & $url & "\">Download</a>"

If a required parameter is missing, the user sees Error downloading file: a required parameter is missing or malformed. Please double-check your request, or contact your Quickbase support representative if the issue persists. If no file is given, the message is Error downloading file: no file was specified to download. See XL Docs messages and troubleshooting.

Merge other PDFs into the document

With docfmt=pdf, you can add other PDF files to the generated document—for example a cover letter before it, or your terms and conditions after it. prefiles lists files to put before the generated PDF and addfiles lists files to put after it, in the order you list them. Separate items with periods. Each item can be:

& "&docfmt=pdf"
& "&prefiles=15"                                  // cover letter on this record
& "&addfiles=" & [_DBID_TERMS] & ":1:6" & ".16"   // terms record 1, then field 16 on this record

• prefiles and addfiles together can list up to 10 files by default; your account's limit may differ. If you list more than your limit, the request stops with You cannot merge more than <limit> addfiles/prefiles file(s). Please open a Quickbase support ticket for further information., for example You cannot merge more than 10 addfiles/prefiles file(s).

• With any format other than PDF, the request stops with The 'addfiles'/'prefiles' parameters are only supported when 'docfmt' is 'pdf'.

• If a listed field is empty on the record, it's skipped and the document is created without it.

Merge many records into one PDF

With msqry and docfmt=pdf, XL Docs can combine every record's PDF into one file and save it on a single record—for example, all employee expense sheets for a project, saved on the project. Each record's document is still saved as usual (for example in its faid field), except the last record processed: its document goes into the merged PDF instead of its own field.

This button on a Project record creates an expense sheet for each employee on the project, saves each one on the Project Employee record, and saves one merged PDF on the project:

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_PROJECT_EMPLOYEES]
& "&tpdbid=" & [_DBID_DOCUMENT_TEMPLATES]
& "&tpid=36"
& "&fn=My_Project_Expenses_" & ToText(Today())
& "&msqry={'6'.EX.'" & URLEncode([Record ID#]) & "'}"
& "&faid=62"
& "&xlddte=63"
& "&docfmt=pdf"
// Merging documents
& "&mrgdbid=" & Dbid()
& "&mrgfa=242"
& "&mrgrid=" & URLEncode([Record ID#])
& "&mrgfn=ALL_Project_Employee_Expense_Sheets"
& "&mrgdte=243";

"<a class='Vibrant Success OpenAsPopup POSTTempToken' data-height=400 data-width=800 data-refresh=true data-temptokendbid='" & [_DBID_PROJECT_EMPLOYEES] & "' href=\"" & $url & "\">Create ALL Project Employee Expense Sheets</a>"

In the installation wizard's bulk document generation, the Merge Output Files option sets this up for you and saves the merged file on the control table record the run was started from. Merging works only when the Output File Type is PDF; with another format, the request stops with The 'mrgdbid'/'mrgfa'/'mrgrid' parameters are only supported when 'docfmt' is 'pdf'.

Put many records in one workbook

With msqry, sameworkbook=y creates one workbook with a worksheet (tab) for each record instead of a document per record. Because there's only one file, it can be streamed to the browser.

• snfid—a field whose value names each tab, for example an employee name. Only letters, numbers, spaces, and - | + @ # $ & ( ) _ , . ! ^ are kept. Without it, tabs are named from the template tab with a number: <tab>_1, <tab>_2, and so on.

• swbdbid, swbrid, swbfaid—the table, record, and file attachment field to save the workbook on. All three are needed.

& "&msqry={'6'.EX.'" & [Record ID#] & "'}"
& "&sameworkbook=y"
& "&snfid=9"
& "&swbdbid=" & Dbid()
& "&swbrid=" & [Record ID#]
& "&swbfaid=155"

If XL Docs can't add or name the tabs, the message is Error occurred while adding new tabs for 'Same Workbook' mode. or Error occurred while naming new tabs for 'Same Workbook' mode. See XL Docs messages and troubleshooting.

Questions? Submit a technical support case.