Run a package in the background

A background run builds a package with no window open. A Quickbase email notification sends the record's Package Builder arguments to us; Package Builder runs every step in the sequence on our servers and writes the result to the record's status field when it's done. Use it to build packages automatically when a record changes, for many records at once (see Run packages for many records), or when steps take longer than a user should wait.

To build a package while the user watches, see Run a package from a button.

How it works

1. Something on the record changes that your email notification watches for—for example, a user, a button, or an automation sets Package Builder Status to text that starts with Package Builder Execution Requested.

2. The email notification on the master table fires and sends one email to the Package Builder address. Its body is the value of Package Builder Batch Arguments for that record.

3. Package Builder checks the arguments against your batch configuration (configid), then runs each step in the sequence, in order. Each step's extension checks that step's arguments against its own batch configuration.

4. When the run ends, Package Builder writes the result to Package Builder Status and adds a record per step to Package Builder Run Details.

Package Builder starts a run only when the request address receives the arguments. It doesn't watch your records and doesn't look at the value that fired the notification, so Package Builder Execution Requested is a convention this article uses, not a value Package Builder needs. The installation wizard creates the Package Builder Batch Email and Package Builder Batch Arguments fields, but—unlike the installation wizards of Exact Forms Plus or XL Docs—it doesn't create a trigger field, an Execute button, or the email notification. You create the notification and choose what fires it, as described below.

Package Builder doesn't send an email when it's done. Check the status field, or add your own notification on it.

Addresses and type

Use the address and type value for your account's region. The installation wizard puts the right address in the Package Builder Batch Email field and the right type in Package Builder Batch Arguments.

The address and type must match each other.

The batch arguments

The installation wizard creates Package Builder Batch Arguments, a Formula - Text field. Parameters are separated by spaces, with no base address:

"clientid=Q1234"  // your Client ID
& " appid=" & AppID()
& " dbid=" & Dbid()
& " msid=" & [Record ID#]
& " tpdbid=" & [_DBID_DOCUMENT_TEMPLATES]
& " apptoken="  // only if your app requires application tokens
& " pckgsq=" & [Package Builder Template Sequence]
& " stsfid=51"  // Package Builder Status
& " rddbid=" & [_DBID_PACKAGE_BUILDER_RUN_DETAILS]
& " rdrelfid=6"
& " rdadnfid=8"
& " rdntsfid=7"
& " configid=<your Config Key>"  // the batch configuration the wizard created
& " type=packagebuilder"  // packagebuildereu for EU accounts

• The field IDs (51, 6, 8, 7) are examples; the wizard fills in your own. Q1234 stands for your Client ID; see Find your Client ID, table IDs, and field IDs.

• Start every added parameter with a space, for example & " mergeargsfid=60" for an automatic final merge (see Merge a package into one PDF).

• A value that contains spaces must be in double quotes.

• Every parameter is explained in Formula URL parameters.

The batch configuration (configid)

Every background run must name a batch configuration with configid, and its parameters must match it. The wizard creates a configuration for Package Builder in the Batch Configuration Portal that pins clientid and appid to your Client ID and this app, and adds its key to the batch arguments for you.

• If configid is missing, no configuration has that key, or a pinned parameter doesn't match exactly (values are case-sensitive), nothing is built. The reason is written to Package Builder Status, for example The following parameters do not match the configuration: [appid] on 10/6/2026 2:15:07 PM.

• If you copy the app, the copy has a new app ID, so add it to the configuration's allowed values (or create a configuration for the copy) before you run packages from it.

• Parameters the configuration doesn't list aren't checked. To lock down more—such as pckgsq or stsfid—add them in the portal.

See Batch Config Portal overview and Use a configuration in batch runs.

Each step's own batch configuration

Package Builder's configuration covers only Package Builder's own arguments. Batch configuration checking is on for every account, and each step runs its extension in batch, so each step's arguments are also checked against that extension's configuration:

• Each step's arguments must include configid=<that extension's Config Key>. The extension's installation wizard adds it to the arguments field it creates.

• Their values must be allowed by that configuration. The Exact Forms Plus, XL Docs, and PDF Stamper wizards' configurations allow only their own output field in faid, only empty merge options, and only the wizard's repository table (or an empty value) in rpdbid and rpfafid.

• If you change a step's faid, or add repository or merge options to a step, update that extension's configuration in the Batch Config Portal first. Otherwise the step fails, or its document isn't created.

See Each step's own batch configuration, Create and manage batch configurations, and Use a configuration in batch runs.

Create the email notification

These steps start a run when Package Builder Status is set to text that starts with Package Builder Execution Requested. The status field works well as the trigger because Package Builder replaces its value with the result when the run ends, which also resets the trigger. You can use any other condition that suits your workflow, such as a checkbox or your own trigger field; the notification only has to send the arguments once per run.

1. Open the table's notifications. In your app, select ... (more options) next to the master table in the left bar, then select Notifications, subscriptions & reminders.

2. Create a notification. Select + New Email. In Create a New Email, select Notification (Send automated notifications based on specific criteria), then select Create.

3. Set the permission type. Select Open: Emails sent openly to anyone.

4. Name it, for example Run Package Builder.

5. Set the recipient. Under Notify whom, type the Package Builder address for your region in the email addresses box (see Addresses and type), or choose the Package Builder Batch Email field, which holds that address. While you're testing, add your own address too, so you can see when the notification fires and what it sends. Remove it later.

6. Choose when it fires. Under Notification when, choose the first option: a <record> is modified (the wording uses your table's record name, such as a Project is modified).

7. Add the criteria. Select Additional criteria, then Any of the following field changes, and check Package Builder Status. Under AND when the following conditions are true after the change, choose all and set the condition to Package Builder Status starts with the value Package Builder Execution Requested.

8. Set the message type and subject. Under Email Contents, select Custom message. Enter a subject such as Run Package Builder - Your Company. Your company name in the subject helps with troubleshooting but isn't required.

9. Add the arguments. On the Single record version tab, in the message body, use Choose fields & markers to insert Package Builder Batch Arguments. The body must contain only this field: no greeting, signature, or other text.

10. Add the arguments for several records. On the Multiple record version tab, enter the same field between the repeat markers, each on its own line:

    %RepeatOn%
    [Package Builder Batch Arguments]
    %RepeatOff%

    Quickbase uses this version when several records change in the same action, such as a Grid Edit or an import. It repeats the line once for each record, so each record's arguments are on their own line, and each line becomes its own run. Again, add no other text.

11. Preview it. Select Preview and check that the body shows the arguments on one line and includes configid= and the type= value for your region.

12. Save the notification.

Note

If Quickbase shows a Notification Error when you save, saying your account may only send email to verified Quickbase users, submit a technical support case to allow your account to send emails to non-registered Quickbase users. See also Quickbase enhanced security email notifications.

Request a run

Set Package Builder Status to text that starts with Package Builder Execution Requested—for example Package Builder Execution Requested on 10/6/2026 2:10 PM. You can do it by editing the record, from a Quickbase pipeline or automation, or with a button that updates the field. Adding the date and time makes each request a change, so the notification fires every time.

Setting this text doesn't do anything by itself: it only fires your notification, and the notification sends the arguments. When the run ends, Package Builder replaces the field's value with the result. That new value doesn't start with Package Builder Execution Requested, so it doesn't start another run.

Run packages for many records

Each background run builds the package for one record, but you can request runs for many records at once. Set Package Builder Status to the request text on all of them—for example with Grid Edit on a report of the records you want, by importing the value, or with a Quickbase pipeline that updates the records. Each record that changes is sent as its own line (with the Multiple record version from the steps above), gets its own run, and gets its own result in its status field.

The runs are queued and processed in turn, so a large set of records takes a while to finish. To see which records are done, add Package Builder Status to the report.

What changes in the status field

In these messages, <Add-on> is the template's Add-On value, such as XL Docs.

The date and time are our server's. For every message and what to do, see Package Builder messages and troubleshooting and Run details and status.

If the status field still shows your request after the steps should have finished, check that the notification fired (the copy to your own address), that the address and type are for the same region, and that the arguments include every required parameter.

Differences from a button run

• No per-step time limit. A step can run as long as its extension needs; there's no 5-minute limit as in the pop-up.

• No window. Nobody has to keep a window open, and the run isn't affected by the user's session.

• Package Builder's batch configuration required. Background runs need a matching configid for Package Builder; button runs instead rely on the enhanced security button's temporary token. Each step's own configuration is checked either way.

• Same results. The documents, status field, and Run Details records are the same as for a button run.

Learn more

• Set up a package

• Formula URL parameters

• Use a configuration in batch runs

If you have questions, submit a technical support case.