---
title: "Use a configuration in batch runs"
slug: "batch-config-portal-use"
updated: 2026-10-09T18:17:30Z
published: 2026-10-09T18:17:30Z
canonical: "help.quickbase.com/batch-config-portal-use"
---

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

# Use a configuration in batch runs

A batch configuration only protects a batch run when the run's arguments name it. This article explains how to add the Config Key to your batch arguments, exactly how a run's parameters are checked against the configuration, and which extensions check them.

*Available to:* anyone who builds batch arguments in a Quickbase app (formula fields, code pages, or email notifications). Copying a Config Key requires a role that can open **My Extensions** in the Extensions Portal.

## Add the Config Key to your batch arguments

Batch arguments are a list of *name=value* parameters separated by spaces. To tell the extension which configuration to check, add one more parameter:

```plaintext
configid=<your Config Key>
```

Use the **full** Config Key, not the 8 characters shown in the portal's grid.

You can also write the parameter as *configkey=<your Config Key>*. If the arguments include both *configkey=* and *configid=*, the extension uses *configkey*.

> [!NOTE]
> Note
> 
> The names can be confusing: the parameter is named **configid** (or **configkey**), its value is the configuration's **Config Key** as shown in the portal, and the error messages call it **ConfigID**. All three mean the same key. QB Courier and Text My QB notifications also have a *configid=* parameter, but there it's the number of a Courier or Text My QB configuration, not a batch configuration's Config Key. See [Quickbase enhanced security email notifications](https://help.quickbase.com/quickbase-extensions/docs/en/quickbase-enhanced-security-email-notifications).

1. In the Batch Configuration Portal, open the extension's **Configurations** screen and copy the configuration's full key: select the key or its copy icon. See [Copy the Config Key](https://help.quickbase.com/quickbase-extensions/docs/en/batch-config-portal-manage#copy-the-config-key).
2. In your Quickbase app, open the place where the batch arguments are built:
  - Usually the extension's batch arguments formula field (for example **XL Docs Batch Processing Arguments**), which the email notification sends. Each extension's field is listed in [Extensions that check batch configurations](https://help.quickbase.com/quickbase-extensions/docs/en/batch-config-portal-use#extensions-that-check-batch-configurations).
  - Or the body of the email notification itself, if the arguments are typed there.
  - Or the code page or script that builds the arguments.
3. Add *configid=* followed by the key, separated from the other parameters by a space. If *configid=* is already there, replace its value. Don't add spaces inside the parameter.
4. Save the field or notification.

If the installation wizard set up your batch processing, it already added *configid=* with the key of the configuration it created. Keep that value unless you want the run to use a different configuration. The Image Resizer/Rotator wizard doesn't create one: [submit a technical support case](https://help.quickbase.com/docs/get-help-from-quickbase-technical-support) to have the first configuration created, then add its key.

### Example: Batch Processing Arguments formula

A Formula - Text field that builds batch arguments. Your extension's parameters will differ; the part that matters here is the last line.

```plaintext
"clientid=Q#"  // Q followed by your Client ID number
& " appid=" & AppID()
&" dbid=" & Dbid()
&" tpid=3"
& " faid=39"  // the field the output is saved to
& " msid=" & [Record ID#]
&" configid=<your Config Key>"  // copied from the Batch Configuration Portal
```

On a record, the field's value looks like this (this is also the text you'd paste with **Paste Parameters**):

```plaintext
clientid=Q# appid=<your app ID> dbid=<your table ID> tpid=3 faid=39 msid=12 configid=<your Config Key>
```

Replace *Q#* and the field and table 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).

## How parameters are checked

Every time a batch run starts, the extension reads *configid=* (or *configkey=*) from the arguments, finds the configuration with that Config Key, and compares the run's parameters with it:

- **The Config Key is required.** If the arguments don't include *configid=* or *configkey=*, or no configuration has that key, the run stops.
- **Each parameter the run passes must match.** For every parameter in the arguments that's also listed in the configuration, the value passed must equal one of that parameter's allowed values. If any doesn't, the run stops and the error names the parameters that didn't match.
- **Parameter names aren't case-sensitive.** *FAID=39* and *faid=39* are checked against the same parameter.
- **Values are case-sensitive and must match exactly.** *Invoice* doesn't match an allowed value of *invoice*. Spaces and punctuation count.
- **Up to 10 allowed values per parameter.** A parameter matches if the value passed equals any one of them.
- **A *blank* allowed value allows an empty value**, for example *apptoken=* with nothing after the *=*.
- **Parameters that aren't in the configuration aren't checked.** To lock one down, add it in the portal (see [Add a parameter](https://help.quickbase.com/quickbase-extensions/docs/en/batch-config-portal-manage#add-a-parameter)).
- **A configured parameter that the run leaves out isn't checked.** Only the parameters the run actually passes are compared, so leaving one out of the arguments doesn't stop the run.
- **Don't pass a checked parameter twice.** If the same configured parameter appears more than once in the arguments, the run stops.
- Each parameter is split at its first *=*, so a value can itself contain *=*.

### Worked example

Suppose a configuration has these parameters:

| **Parameter Name** | **Allowed Value(s)** |
| --- | --- |
| clientid | Q# |
| appid | bq1234567 |
| faid | 39, 40 |
| fn | Invoice |
| apptoken | *blank* |

Here's how different values in a run's arguments are checked:

| **Parameter** | **Allowed values** | **Passed value** | **Result** |
| --- | --- | --- | --- |
| faid | 39, 40 | faid=40 | Matches (40 is allowed). |
| faid | 39, 40 | faid=41 | Doesn't match. The run stops. |
| faid | 39, 40 | FAID=39 | Matches (names aren't case-sensitive). |
| faid | 39, 40 | (left out of the arguments) | Not checked. The run continues. |
| fn | Invoice | fn=invoice | Doesn't match (values are case-sensitive). The run stops. |
| apptoken | *blank* | apptoken= | Matches (an empty value is allowed). |
| apptoken | *blank* | apptoken=abc123 | Doesn't match (only an empty value is allowed). The run stops. |
| appid | bq1234567 | appid=bq1234567 … appid=bq7654321 | Passed twice. The run stops. |
| tpid | (not in the configuration) | tpid=3 | Not checked. |

If the run passed *faid=41* and *fn=invoice*, it would stop with *The following parameters do not match the configuration: [faid, fn]*. For every message and what to do, see [Batch Config Portal messages and troubleshooting](https://help.quickbase.com/quickbase-extensions/docs/en/batch-config-portal-messages).

## Extensions that check batch configurations

These extensions check batch configurations on every batch run:

| **Extension** | **Batch arguments field the wizard creates** | **Wizard creates a configuration and adds configid?** | **Where you see a failed check** | **Extension's batch article** |
| --- | --- | --- | --- | --- |
| XL Docs | **XL Docs Batch Processing Arguments** | Yes | Bulk setup: the **Trigger Field** on the XL Docs Batch Processing record. Single-record setup: nowhere in your app by default. To see the message on the record, add *xldbdbid*, *xldbrid*, and *xldbtfld* to the **XL Docs Batch Processing Arguments**. | [XL Docs batch processing](https://help.quickbase.com/quickbase-extensions/docs/en/xl-docs-batch-processing) |
| PDF Stamper | **PDF Stamper Batch Processing Arguments** (single-record setup) or **Batch Processing Arguments** (bulk setup) | Yes | Nowhere in your app. The run stops without writing a status. | [Setting Up Batch](https://help.quickbase.com/quickbase-extensions/docs/en/setting-up-batch) |
| QB Maps | **QBMaps Console Arguments** (geocoding setup), or **QBMaps Geocoding Console Arguments** and **QBMaps Distance Console Arguments** (distance setup) | Yes, one for each arguments field | Distance runs: the **QB Maps Distance Status** field shows *Distance failed to be updated at: <date and time> Error:<message>*. Geocoding runs: nowhere in your app. | [Batch features and functionality](https://help.quickbase.com/quickbase-extensions/docs/en/batch-features-and-functionality) |
| Exact Forms Plus | **Batch Processing Arguments** | Yes | Single-record setup: the **EFP Batch Trigger - Msg Field** on the record. Bulk setup: the **Trigger Field** on the Batch Processing record, plus a record in the Batch Processing Logs and Batch Processing Errors tables. The text starts with *ERROR ENCOUNTERED_* and the date and time, followed by the message. | [Exact Forms Plus Batch Processor overview](https://help.quickbase.com/quickbase-extensions/docs/en/efp-batch-processor-overview) |
| JuicedSign | **JuicedSign Batch Arguments** (after your field prefix, if you entered one in the wizard) | Yes | The **JuicedSign Error Details** field on the record. The field shows the message on its own. | [JuicedSign batch processing](https://help.quickbase.com/quickbase-extensions/docs/en/batch-processing) |
| PDF Merger | **PDF Merger Parameters** | Yes | The **Merger Error Details** field on the record. The message starts with *Error occured merging documents -*. | [PDF Merger email notification setup](https://help.quickbase.com/quickbase-extensions/docs/en/pdf-merger-email-notification-setup) |
| Package Builder | **Package Builder Batch Arguments** | Yes | The **Package Builder Status** field on the record. The field shows the message, then *on* and the date and time. | [Run a package in the background](https://help.quickbase.com/quickbase-extensions/docs/en/package-builder-run-in-the-background) |
| Image Resizer/Rotator | None. You create the **Batch Processing Arguments** field yourself. | No. [Submit a technical support case](https://help.quickbase.com/docs/get-help-from-quickbase-technical-support) to have the first configuration created, then add *configid=* with its Config Key. | Nowhere in your app. The trigger field keeps its *Requested* value. | [Image Resizer/Rotator batch processing](https://help.quickbase.com/quickbase-extensions/docs/en/image-resizer-rotator-batch-processing) |

**Docusign for Quickbase** and **EZ File Importer**: the installation wizard also creates a batch configuration for them (for the **Docusign Batch Arguments** and **Import Generation Arguments** fields), so they're listed on **Batch Add-Ons**. Their batch runs don't check it, so a changed value never stops their runs and editing those configurations has no effect. For Docusign batch runs, see [Docusign batch email notification](https://help.quickbase.com/quickbase-extensions/docs/en/docusign-batch-create-email-notification).

Use the portal when you change the batch arguments afterward, for example to save output to a different field, so that the configuration allows the new values.

> [!NOTE]
> Note
> 
> When you change a value in your batch arguments, update the configuration's allowed values first. Otherwise the next run stops with a mismatch error.

## Learn more

- [Batch Config Portal overview](https://help.quickbase.com/quickbase-extensions/docs/en/batch-config-portal-overview)
- [Create and manage batch configurations](https://help.quickbase.com/quickbase-extensions/docs/en/batch-config-portal-manage)
- [Batch Config Portal messages and troubleshooting](https://help.quickbase.com/quickbase-extensions/docs/en/batch-config-portal-messages)