---
title: "Batch processing"
slug: "xl-docs-batch-processing"
updated: 2026-10-09T18:09:07Z
published: 2026-10-09T18:09:07Z
canonical: "help.quickbase.com/xl-docs-batch-processing"
---

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

# Batch processing

Batch processing runs XL Docs in the background, with no window for the user to wait on. A Quickbase email notification sends the processing arguments to the XL Docs batch processor, which creates the documents, saves them on your records, and writes its status back to a field on the record that started the run.

Use batch processing to:

- Create documents in bulk—more than a single button click can create (up to 50 by default; your account's limit may differ; see [Generate documents for multiple records](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-multiple-records)).
- Create documents automatically when something happens to a record—for example, when a record is saved, when several records are changed with grid edit, or when records are imported—so nobody has to click a button.

The batch processor works like the web version of XL Docs and accepts the same parameters (see [Formula URL parameters](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-url-parameters)), so a template that works from a button works in batch too.

## How it works

1. Something changes on the record—a user clicks the **Execute Batch** button, or another change you choose happens—and the **trigger field** is updated to contain *Requested* (the button writes *Batch Execution Requested_* followed by the date and time).
2. A Quickbase email notification on that table fires and sends the **XL Docs Batch Processing Arguments** field to the XL Docs batch address.
3. The batch processor reads the arguments, finds the records in **msqry** (or the single record in **msid**), and creates and saves the documents.
4. When it's done, it updates the trigger field (the field in **xldbtfld**) on the record in **xldbrid**: *PROCESS COMPLETED_* followed by the date and time, or the error message if something went wrong. If you use a log table (**logsdbid**), it also adds a log record. For a single-record run you can use **triggerfid** instead (see [Status on the record (triggerfid)](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-batch-processing#status-on-the-record-triggerfid)).

## Typical example

To create documents in bulk, an app usually has a **control** table: a record high up in the relationships—a Projects record, for example—that drives the creation of documents for records in a child table. For one Project you might want an expense statement for every employee on the project. With up to 50 employees, a button can do this (see [Generate documents for multiple records](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-multiple-records)). With more than 50, use the batch processor.

## What the installation wizard installs

The installation wizard installs everything batch processing needs. What you get depends on the setup type you choose (see [XL Docs setup type](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-setup-type)).

### Single document generation setup

The wizard adds these batch fields to the table you selected, next to the buttons that create documents from a click. Use them to create a record's document automatically when the record changes.

| **Field** | **Purpose** |
| --- | --- |
| XL Docs Batch Processing Arguments | Formula - Text. The parameters sent to the batch processor (see [Batch processing arguments](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-batch-processing#batch-processing-arguments)). |
| XL Docs Batch Trigger Field | Text. Updated when the button is clicked; the change sends the email notification. To see the run's status here, add **triggerfid** with this field's ID to the arguments (see [Status on the record (triggerfid)](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-batch-processing#status-on-the-record-triggerfid)). |
| Execute XL Docs Batch | A button that writes the request into the trigger field (see [Execute Batch button](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-batch-processing#execute-batch-button)). |
| XL Docs Batch Email | Formula - Email. The XL Docs batch address for your account (*xldocsbatch@xldocsbatch.quickbasetools.com*, or *xldocsbatcheu@xldocsbatch.quickbasetools.com* if your account is hosted in the EU). |

### Bulk document generation setup

The wizard creates two tables:

- **XL Docs Batch Processing**—the control table. You start a batch run from a record in this table.
- **XL Docs Batch Processing Logs**—one record per run, with what happened: the start and end time, the number of documents processed, and any errors.

The XL Docs Batch Processing table has these fields:

| **Field** | **Purpose** |
| --- | --- |
| Name | Text, required. A name for the run. |
| Trigger Field | Text. Shows whether the run has been requested and when it completed. Updated automatically. |
| Execute Batch | A button that starts the run by writing *Batch Execution Requested_* and the current date and time into the Trigger Field. |
| Records to be Processed | Formula - URL. A link that opens the records the run will create documents for (the report or query you chose in the wizard). |
| Processing | Formula - Text with **Allow some HTML tags** turned on. While a run is requested, it shows *<--Processing, refresh your screen until this shows completed*. |
| Refresh | Formula - Text with **Allow some HTML tags** turned on. A **Refresh** button, shown while the run is processing, that reloads the record so you can see when the run has completed. |
| XL Docs Batch Processing Arguments | Formula - Text. The parameters sent to the batch processor. |
| Merged File | File attachment. If you turned on **Merge Output Files** in the wizard, the merged PDF of all documents is saved here. |
| Merged Date | Date/Time. With **Merge Output Files**, set to the date and time the merged PDF was saved. |
| XL Docs Batch Email | Formula - Email. The XL Docs batch address for your account. |
| XL Docs Batch Processing Logs | Report link. Lists this record's runs from the logs table. |

If you chose Amazon S3 storage, the wizard also adds **S3 Key** and **View File** fields (see [Output and storage](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-output-and-storage)).

The XL Docs Batch Processing Logs table has these fields: **Related Batch Processing**, **XL Docs Batch Processing - Name** (a lookup of the run's name), **Status**, **Notes**, **Documents Processed**, **Start**, **End**, and **Run Duration** (a Formula - Duration field: End minus Start). See [Status messages](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-batch-processing#status-messages) for what each run writes.

After the wizard finishes, there is one more step: [create the email notification](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-batch-processing#create-the-email-notification). The wizard's finish page reminds you: *Your setup for generating documents automatically is not finished!*

## Batch processing arguments

The **XL Docs Batch Processing Arguments** formula uses the same parameters as a button (see [Formula URL parameters](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-url-parameters)), with these differences:

- There is **no base address**—no server URL and no page name.
- Parameters are separated by **spaces** instead of *&*. Don't put spaces anywhere else—write *tpid=3*, not *tpid = 3*.
- If a value contains spaces or special characters, wrap it in escaped double quotes: *fn=\"XLD Bulk Document\"*, *msqry=\"({'43'.GT.'0'})\"*.
- **type** tells the batch processor which extension the request is for. For XL Docs it is *xldocsbatch*, or *xldocsbatcheu* if your account is hosted in the EU. The installation wizard sets the right value; it must match the batch address the email notification sends to.
- **xldbdbid**, **xldbrid**, and **xldbtfld** tell the batch processor where to write its status: the table, the record, and the trigger field. Set all three if you want to see when the run is done or why it failed.
- **triggerfid** (optional, single-record runs only) is the field ID of a text field on the record being processed, where the run's status is written. See [Status on the record (triggerfid)](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-batch-processing#status-on-the-record-triggerfid).
- **logsdbid** (optional) is the XL Docs Batch Processing Logs table, where a record is added for each run.
- Keep the **configid** value the installation wizard created. The batch processor always checks the arguments against that batch configuration. See [Batch configurations](https://help.quickbase.com/quickbase-extensions/docs/en/batch-configurations) and [Use a configuration in batch runs](https://help.quickbase.com/quickbase-extensions/docs/en/batch-config-portal-use).

### Example: bulk documents from a control record

```
"clientid=Q#"  // your Client ID
& " appid=" & AppID()
& " dbid=" & [_DBID_PROJECT_EMPLOYEES]  // the table to create documents for
& " tpdbid=" & [_DBID_DOCUMENT_TEMPLATES]
& " tpid=3"
& " fn=\"XLD Bulk Document\""
& " msqry=\"({'43'.GT.'0'})\""
& " faid=39"
& " xlddte=40"
& " docfmt=xlsx"
& " apptoken="  // add your app token after = if your app requires application tokens
& " logsdbid=" & [_DBID_XL_DOCS_BATCH_PROCESSING_LOGS]
& " xldbdbid=" & Dbid()
& " xldbrid=" & [Record ID#]
& " xldbtfld=7"  // the Trigger Field
& " type=xldocsbatch"  // xldocsbatcheu if your account is hosted in the EU
& " configid=..."  // keep the value created by the installation wizard
```

Replace *Q#* and the table, field, and record IDs with your own (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)).

To use a report instead of a query, replace **msqry** with *msqid=* and the report ID. To merge all the documents into one PDF on the control record, set *docfmt=pdf* and add **mrgdbid**, **mrgrid**, **mrgfa** and, optionally, **mrgfn** and **mrgdte**, as described in [Merge all documents into one PDF](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-multiple-records#merge-into-one-pdf).

### Example: one document when a record changes

To create a single record's document automatically, use **msid** for the record itself:

```
"clientid=Q#"
& " appid=" & AppID()
& " dbid=" & Dbid()
& " tpdbid=" & [_DBID_DOCUMENT_TEMPLATES]
& " tpid=1"
& " msid=" & [Record ID#]
& " fn=XLDBDocument"
& " faid=51"
& " xlddte=52"
& " docfmt=pdf"
& " apptoken="
& " xldbdbid=" & Dbid()
& " xldbrid=" & [Record ID#]
& " xldbtfld=53"  // the XL Docs Batch Trigger Field
& " type=xldocsbatch"  // xldocsbatcheu if your account is hosted in the EU
& " configid=..."
```

### Status on the record (triggerfid)

For a single-record run (**dbid** plus **msid**), you can have the batch processor write its status into a text field on that same record by adding **triggerfid** with the field's ID. Multi-record runs (**msqry** or **msqid**) use **xldbdbid**, **xldbrid**, and **xldbtfld** on the control record instead.

- When the run starts, the field is set to *PROCESSING_* followed by the date and time.
- When the run ends, it is set to *PROCESS COMPLETED_* followed by the date and time, or to the error message if the run failed—the same wording as **xldbtfld**.
- If the status can't be written (for example, the field ID is wrong), the document is still created.

The installation wizard doesn't add **triggerfid**. To see the status in the wizard's **XL Docs Batch Trigger Field**, add *triggerfid=* and that field's ID to the **XL Docs Batch Processing Arguments** formula:

```
& " triggerfid=8"  // the XL Docs Batch Trigger Field's ID
```

## Execute Batch button

The installation wizard creates this button for you (**Execute Batch** on the XL Docs Batch Processing table, or **Execute XL Docs Batch** on your table). It's a Formula - URL field that uses the Quickbase API to write *Batch Execution Requested_* and the current time into the trigger field, then returns to the record. While a run is requested, the button is hidden, so users don't start it twice.

```
If(Contains([Trigger Field], "Requested"), "",
  URLRoot() & "db/" & Dbid() & "?"
  & "act=API_EditRecord"
  & "&rid=" & URLEncode([Record ID#])
  & "&_fid_7=Batch Execution Requested_" & ToText(Now())  // 7 = your Trigger Field
  & "&apptoken=[Your App Token]"
  & "&rdr=" & URLEncode(URLRoot() & "db/" & Dbid() & "?"
  & "a=dr"
  & "&rid=" & URLEncode([Record ID#]))
)
```

Replace *[Your App Token]* with an application token from your app's settings, or remove that line if your app doesn't require application tokens. Never publish a real token in shared formulas or documentation.

You don't need the button if documents should be created when something else happens. Any change that writes *Requested* into the trigger field—a form rule, an automation, a grid edit, or an import—starts a run.

## Create the email notification

The email notification is what actually sends the request to the batch processor. Create it on the table that holds the trigger field and the arguments field (for a bulk setup, the XL Docs Batch Processing table).

1. Open the table's **⋯** menu, select **Notifications, subscriptions & reminders**, then select **+ New Email** and choose **Notification**.
2. Set **Permission type** to **Open: Emails sent openly to anyone**.
3. Give the notification a meaningful name, for example *XL Docs Batch Processing*.
4. In **Notify whom**, enter **xldocsbatch@xldocsbatch.quickbasetools.com**. If your account is hosted in the EU, use **xldocsbatcheu@xldocsbatch.quickbasetools.com** (with *type=xldocsbatcheu* in the arguments). You can add other addresses if you want people to be told when someone requests a run.
5. Under **Notification when**, choose the first option: **a record is modified** (the option shows your table's record name, for example *an XL Docs Batch Processing is modified*).
6. Open **Additional criteria**, choose **Any of the following fields change**, and select the trigger field (**Trigger Field** or **XL Docs Batch Trigger Field**).
7. Under the conditions that must be true after the change, choose **all** of these conditions are true and add: the trigger field **contains** **the value** *Requested*.
8. Set **Message type** to **Custom message**, and enter a descriptive **Subject**, for example *XL Docs Batch Request*.
9. In the custom message box, insert only the **XL Docs Batch Processing Arguments** field—pick it from the list of fields beside the message box. Don't add any other text to the message.
10. Select **Save**.

> [!NOTE]
> Note
> 
> The *contains Requested* condition is required. The batch processor writes its status into the trigger field when it finishes; without the condition, that update would fire the notification again and start another run.

> [!WARNING]
> Important
> 
> When you save, Quickbase may show a **Notification Error** saying the account may only send email to verified Quickbase users. If so, [submit a technical support case](https://help.quickbase.com/docs/get-help-from-quickbase-technical-support) to allow your account to send emails to non-registered Quickbase users.

## Status messages

The trigger field (the field in **xldbtfld**, or in **triggerfid**) shows where the run is:

| **Value** | **Meaning** |
| --- | --- |
| *Batch Execution Requested_* + date and time | The button (or your own change) requested a run. The email notification has been sent and the run is waiting or in progress. Refresh the record to see when it completes. |
| *PROCESSING_* + date and time | **triggerfid** only. The run has started. |
| *PROCESS COMPLETED_* + date and time | The run finished and the documents were saved. |
| An error message | The run failed. The message says why—for example, a template or parameter problem. See [XL Docs messages and troubleshooting](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-messages). |

If you set **logsdbid**, each run also adds a record to the XL Docs Batch Processing Logs table, related to the record that started it:

| **Field** | **Value** |
| --- | --- |
| Start / End | When the run started and finished. |
| Run Duration | How long the run took (End minus Start). |
| Status | *Completed* or *Error*. |
| Notes | *Documents Generated Successfully.* or the error message. |
| Documents Processed | How many documents were created. |
| Related Batch Processing | The record in **xldbrid**. |

### Batch configuration messages

The batch processor always checks the arguments against the saved batch configuration (enhanced security) before it creates anything. If the check fails, the run stops and the message is written to the trigger field in **xldbtfld** (when **xldbdbid**, **xldbrid**, and **xldbtfld** are set). The bulk setup sets them, so the message appears in the **Trigger Field** on the XL Docs Batch Processing record. The single-record setup doesn't, so by default the message isn't recorded anywhere; add all three to the **XL Docs Batch Processing Arguments** formula to see it.

| **Message** | **Cause** | **What to do** |
| --- | --- | --- |
| *No ConfigID was passed in. This configuration requires a ConfigID.* | The arguments have no **configid**. | Add the **configid** the installation wizard created back to the arguments. |
| *Could not find a Config with ConfigID <ID> - this configuration requires a ConfigID.* | The **configid** doesn't match a saved configuration. | Check the value, or create the configuration again. |
| *The following parameters do not match the configuration: [<names>]* | The arguments were changed after the configuration was saved. | Update the configuration to match, or change the arguments back. |
| *Encountered duplicate parameter [<name>]* | The same parameter appears twice in the arguments. | Remove one. |
| *No parameters passed in for batch configuration to process.* | The email had no arguments. | Check that the notification's message contains only the **XL Docs Batch Processing Arguments** field. |

See [Use a configuration in batch runs](https://help.quickbase.com/quickbase-extensions/docs/en/batch-config-portal-use) and [Batch Config Portal messages and troubleshooting](https://help.quickbase.com/quickbase-extensions/docs/en/batch-config-portal-messages).

## If nothing happens

- Check that the trigger field contains *Requested* after the click, and that the notification is **Open**, sends to the batch address, and has the *contains Requested* condition.
- Check that the message body contains only the arguments field.
- The batch processor needs **clientid**, **appid**, **fn**, **dbid**, **tpdbid**, **tpid**, and exactly one of **msid** or **msqry**/**msqid**. If any is missing, no documents are created and no status is written. If you give both **msid** and **msqry**, the run stops with *Supply either 'msid' or 'msqry', not both.*
- If your app isn't authorized for XL Docs (for example, its authorization was removed in the Extensions Portal, or the saved user token is no longer valid), the run stops without changing the trigger field. Check the app's authorization in the Extensions Portal (see [Authorization](https://help.quickbase.com/quickbase-extensions/docs/en/step-2-authorization)).
- If the trigger field shows *Batch Execution Requested_* for a long time, [submit a technical support case](https://help.quickbase.com/docs/get-help-from-quickbase-technical-support).