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.

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

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.

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

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

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

What gets installed

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

Document Templates table:

Document Subtable Excel table:

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 and Configure 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). If your app has no wizard-created button, submit a technical support case.

Button parameters

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. For a new XL Docs install, follow XL Docs setup type and XL Docs setup; for an app that already has XL Docs, use Wizard upgrade. See Install the Configurator.

2. Map the master fields on a template: Configure a template.

3. Add data tables for related records: Configure a data table. For a table in another app, see Cross-app subtables.

4. Try the template with your XL Docs button. See Build a document template.

5. If something goes wrong, see XL Docs Configurator messages and troubleshooting.