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:
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
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.
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.
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.
Or the body of the email notification itself, if the arguments are typed there.
Or the code page or script that builds the arguments.
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.
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 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.
"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 PortalOn a record, the field's value looks like this (this is also the text you'd paste with Paste Parameters):
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.
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).
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.
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. | |
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. | |
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. | |
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. | |
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. | |
PDF Merger | PDF Merger Parameters | Yes | The Merger Error Details field on the record. The message starts with Error occured merging documents -. | |
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. | |
Image Resizer/Rotator | None. You create the Batch Processing Arguments field yourself. | No. Submit a technical support case to have the first configuration created, then add configid= with its Config Key. | Nowhere in your app. The trigger field keeps its Requested value. |
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.
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
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.