---
title: "Configurator overview and installation"
slug: "xl-docs-configurator-installation"
updated: 2026-10-09T18:09:40Z
published: 2026-10-09T18:09:40Z
canonical: "help.quickbase.com/xl-docs-configurator-installation"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.quickbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configurator overview and installation

The **XL Docs Configurator** is a point-and-click editor for your XL Docs templates. XL Docs fills your own Excel workbook—with its charts, formulas, data tables, and sheets—with Quickbase data. The Configurator is where you tell it what goes where: individual fields into specific cells, and sets of rows from related tables into specific sheets, even several sets on the same sheet.

Everything the Configurator does is saved in two tables in your app, so you never have to type the configuration by hand:

- **Document Templates**—one record per template: the workbook file, the master table, and the master table's cell mapping. See [Document Templates table reference](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-document-templates-table).
- **Document Subtable Excel**—one record per data table (subtable) in a template: the table to read, the cell mapping, the query, sorting, grid settings, subtotals, grouping, and averages. See [Document Subtable Excel table reference](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-document-subtable-excel-table).

The Configurator also has a **query builder**, so you can build complex filters for data tables the same way you build a Quickbase report filter.

## The two screens

The Configurator has two screens. Each opens in a pop-up from its own button in Quickbase.

| **Screen** | **Opened from** | **Tabs** | **Saves to** |
| --- | --- | --- | --- |
| **XL Docs Configurator** | The **XL Docs Configurator** button on a Document Templates record. | **Fields**, **Images**, **Data Tables** | The Document Templates record. See [Configure a template](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-configurator-configure-a-template). |
| **XL Docs Subtable Configurator** | The **XL Docs Subtable Configurator** button on a Document Subtable Excel record, or **Edit** / **Add New Data Table** on the Data Tables tab. | **Table/Fields**, **Images**, **Data-Grid Settings**, **Query**, **Subtotal/Group** | A Document Subtable Excel record. See [Configure a data table](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-configurator-configure-a-data-table). |

Both screens have **Save** and **Cancel** buttons at the bottom, with the Configurator version beside them. **Save** writes your changes straight to the Quickbase record—there is no separate draft. **Cancel** puts the screen back the way it was when you last opened or saved it. Hover over a field's label to see a tooltip that explains it.

The Configurator doesn't create documents. To try a template, close the Configurator and use your XL Docs button (see [Build a document template](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-build-a-template)).

## Install the Configurator

The Configurator is installed by the installation wizard. How you get it depends on whether XL Docs is already in your app.

### New XL Docs install

When you set up XL Docs with the wizard ([XL Docs setup type](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-setup-type), [XL Docs setup](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-setup)), it creates the Document Templates and Document Subtable Excel tables with all their fields, and adds both Configurator buttons. Nothing else is needed.

### App that already has XL Docs

If XL Docs was installed in your app before the Configurator existed, run the wizard again with **Upgrade Setup**. The wizard adds the missing fields and the Configurator buttons and leaves your templates alone.

1. Go to the [Extensions Portal](https://portal.extensions.quickbase.com/qb/extensionportal).
2. Select **Setup** on the **XL Docs** tile, or open the XL Docs page and select **Authorize New App**. You aren't authorizing a new app—either button opens the installation wizard. Don't use **Setup Table**: it skips the Application information step, so the Upgrade Setup checkbox isn't shown.
3. Follow the shared wizard steps to [Application information](https://help.quickbase.com/quickbase-extensions/docs/en/step-3-application-information). Select your app, then check **Upgrade Setup**.
4. Select **Finish**. The wizard lists what it added—for example, *avlist* and *XL Docs Subtable Configurator* on the Document Subtable Excel table and *XL Docs Configurator* on the Document Templates table—or tells you the app is already up to date.

For details, see [Wizard upgrade](https://help.quickbase.com/quickbase-extensions/docs/en/wizard-upgrade-from-step-3-above).

### What gets installed

The wizard creates any of these fields that are missing. Existing fields are not changed.

**Document Templates** table:

| **Field** | **Type** |
| --- | --- |
| Name | Text |
| clist | Text |
| Template File | File attachment |
| Master table dbid | Text |
| Master table name | Text |
| MSG_DetailsNotFound | Text |
| Excel Sheet # | Numeric |
| PDF Pages | Text |
| Document Subtable Excel DBID | Formula - Text |
| Add New XL Document Subtable | Formula - URL (the standard Quickbase add-record button) |
| XL Docs Configurator | Formula - Text with "Allow some HTML tags" (the button that opens the Configurator) |

**Document Subtable Excel** table:

| **Field** | **Type** |
| --- | --- |
| Related Document Template | Numeric (relationship to Document Templates) |
| Description, dbid, clist, slist, slist Options, qry, stlist, grouplist, avlist | Text |
| Is Data Grid?, EachRecordasNewTab | Checkbox |
| Sheet, Max Line items, Skip Rows | Numeric |
| Max Lines type | Text (choices *Insert New Rows*, *Insert New Tab*) |
| Tab sub report order | Text (choices *01* to *05*) |
| Link to table | URL |
| XL Docs Subtable Configurator | Formula - Text with "Allow some HTML tags" (the button that opens the Subtable Configurator) |

## Add the buttons yourself

If you'd rather add the buttons by hand—for example, on a copy of the tables—create these fields. Both are **Formula - Text** fields with **Allow some HTML tags** turned on, and follow the Quickbase enhanced-security pattern; *data-temptokendbid* is *Dbid()*, the table the button is on (see [Change formula fields](https://help.quickbase.com/quickbase-extensions/docs/en/changing-formula-fields) and [Configure pop-ups](https://help.quickbase.com/quickbase-extensions/docs/en/configuring-pop-ups)).

### Button on the Document Templates table

Field name: **XL Docs Configurator**.

```
var text url = "https://.../Master?"  // your XL Docs Configurator server URL, created by the installation wizard
& "qspclientid=Q#"  // your Client ID
& "&appid=" & AppID()
& "&apptoken="
& "&templatedbid=" & Dbid()
& "&tpid=" & [Record ID#]
& "&subtabledbid=" & [_DBID_DOCUMENT_SUBTABLE_EXCEL];

"<a class='Vibrant Success OpenAsPopup POSTTempToken' data-height=1000 data-width=1400 data-refresh=true data-temptokendbid='" & Dbid() & "' href=\"" & $url & "\">XL Docs Configurator</a>"
```

### Button on the Document Subtable Excel table

Field name: **XL Docs Subtable Configurator**.

```
var text url = "https://.../Subtable?"  // your XL Docs Configurator server URL, created by the installation wizard
& "qspclientid=Q#"  // your Client ID
& "&appid=" & AppID()
& "&apptoken="
& "&templatedbid=" & [_DBID_DOCUMENT_TEMPLATES]
& "&tpid=" & [Related Document Template]
& "&subtabledbid=" & Dbid()
& "&msdbid=" & [dbid]
& "&msid=" & [Record ID#];

"<a class='Vibrant Success OpenAsPopup POSTTempToken' data-height=1000 data-width=1400 data-refresh=true data-temptokendbid='" & Dbid() & "' href=\"" & $url & "\">XL Docs Subtable Configurator</a>"
```

Replace *https://...* with your designated XL Docs Configurator URL—the same server your XL Docs buttons use, created by the installation wizard—and *Q#* with your Client ID. The installation wizard writes your Client ID into every button it creates, as the value that starts with *Q*: *qspclientid=Q…* in the Configurator buttons and *clientid=Q…* in the XL Docs buttons. Open one of those buttons' formulas and copy the server URL and the *Q…* value from it (see [Find your Client ID, table IDs, and field IDs](https://help.quickbase.com/quickbase-extensions/docs/en/find-client-id-table-ids-field-ids)). If your app has no wizard-created button, [submit a technical support case](https://help.quickbase.com/docs/get-help-from-quickbase-technical-support).

### Button parameters

| **Parameter** | **Description** | **Sample in formula** |
| --- | --- | --- |
| qspclientid | Your Quickbase Extensions Client ID: *Q* followed by your client number. Required. Copy it from a wizard-created button (see [Find your Client ID, table IDs, and field IDs](https://help.quickbase.com/quickbase-extensions/docs/en/find-client-id-table-ids-field-ids)). | *qspclientid=Q#* |
| appid | The app the Configurator works in. The Table lists show this app's tables. | *"&appid=" & AppID()* |
| apptoken | Leave empty. | *&apptoken=* |
| templatedbid | The Document Templates table. Required on the Subtable button. | *"&templatedbid=" & Dbid()* |
| tpid | Record ID# of the Document Templates record. Required on the Master button. On the Subtable button, use the Related Document Template field. | *"&tpid=" & [Record ID#]* |
| subtabledbid | The Document Subtable Excel table. Required on the Subtable button. | *"&subtabledbid=" & [_DBID_DOCUMENT_SUBTABLE_EXCEL]* |
| msdbid | Subtable button only: the table the data table reads (the record's *dbid* field). | *"&msdbid=" & [dbid]* |
| msid | Subtable button only: Record ID# of the Document Subtable Excel record to open. Without it, the screen opens a new data table. | *"&msid=" & [Record ID#]* |

Buttons created before the Configurator was updated that point to *Master.aspx* or *Subtable.aspx* still work.

## Get started

1. **Install the Configurator** with the installation wizard. Read the [installation wizard overview](https://help.quickbase.com/quickbase-extensions/docs/en/juiced-add-on-installation-wizard-overview). For a new XL Docs install, follow [XL Docs setup type](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-setup-type) and [XL Docs setup](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-setup); for an app that already has XL Docs, use [Wizard upgrade](https://help.quickbase.com/quickbase-extensions/docs/en/wizard-upgrade-from-step-3-above). See [Install the Configurator](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-configurator-installation#install-the-configurator).
2. **Map the master fields** on a template: [Configure a template](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-configurator-configure-a-template).
3. **Add data tables** for related records: [Configure a data table](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-configurator-configure-a-data-table). For a table in another app, see [Cross-app subtables](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-configurator-cross-app-subtables).
4. **Try the template** with your XL Docs button. See [Build a document template](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-build-a-template).
5. **If something goes wrong**, see [XL Docs Configurator messages and troubleshooting](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-configurator-troubleshooting).