--- title: "Run a package in the background" slug: "package-builder-run-in-the-background" updated: 2026-10-09T18:17:52Z published: 2026-10-09T18:17:52Z canonical: "help.quickbase.com/package-builder-run-in-the-background" --- > ## 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. # 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](https://help.quickbase.com/quickbase-extensions/docs/en/package-builder-run-in-the-background#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](https://help.quickbase.com/quickbase-extensions/docs/en/package-builder-run-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**. | **Region** | **Send the notification to** | **type= value in the arguments** | | --- | --- | --- | | US | *packagebuilder@mail.quickbasetools1.com* | *type=packagebuilder* | | EU | *packagebuildereu@mail.quickbasetools.com* | *type=packagebuildereu* | 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="  // 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](https://help.quickbase.com/quickbase-extensions/docs/en/find-client-id-table-ids-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](https://help.quickbase.com/quickbase-extensions/docs/en/package-builder-merge-into-one-pdf)). - A value that contains spaces must be in double quotes. - Every parameter is explained in [Formula URL parameters](https://help.quickbase.com/quickbase-extensions/docs/en/package-builder-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](https://help.quickbase.com/quickbase-extensions/docs/en/batch-config-portal-overview) and [Use a configuration in batch runs](https://help.quickbase.com/quickbase-extensions/docs/en/batch-config-portal-use). ### 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=*. 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](https://help.quickbase.com/quickbase-extensions/docs/en/package-builder-set-up-a-package#each-steps-batch-configuration), [Create and manage batch configurations](https://help.quickbase.com/quickbase-extensions/docs/en/batch-config-portal-manage), and [Use a configuration in batch runs](https://help.quickbase.com/quickbase-extensions/docs/en/batch-config-portal-use). ## 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](https://help.quickbase.com/quickbase-extensions/docs/en/package-builder-run-in-the-background#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 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] > 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](https://help.quickbase.com/docs/get-help-from-quickbase-technical-support) to allow your account to send emails to non-registered Quickbase users. See also [Quickbase enhanced security email notifications](https://help.quickbase.com/quickbase-extensions/docs/en/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, ** is the template's **Add-On** value, such as *XL Docs*. | **Status field shows** | **What happened** | | --- | --- | | Your request, such as *Package Builder Execution Requested on …* | The run hasn't finished yet (or hasn't started). | | *Process Successfully Completed on * | Every required step worked. If a not-required step failed, a line is added for it: *Error Encountered on - Template # *. | | *Error Encountered on - Template # on * | A required step failed, and the steps after it didn't run. For the automatic final merge from **mergeargsfid**, it's *Error Encountered on PDF Merger on *. To find out why, see [A step failed: where that extension records why](https://help.quickbase.com/quickbase-extensions/docs/en/package-builder-messages#where-a-step-records-why). | | *Package builder failed. Error details : on * | The package couldn't be run, for example because the template sequence lists a Record ID# that isn't in the Document Templates table. | | A batch configuration message, such as *No ConfigID was passed in. This configuration requires a ConfigID.* or *The following parameters do not match the configuration: []*, followed by *on * | The arguments don't match Package Builder's batch configuration. Nothing was built. | The date and time are our server's. For every message and what to do, see [Package Builder messages and troubleshooting](https://help.quickbase.com/quickbase-extensions/docs/en/package-builder-messages) and [Run details and status](https://help.quickbase.com/quickbase-extensions/docs/en/package-builder-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](https://help.quickbase.com/quickbase-extensions/docs/en/package-builder-set-up-a-package) - [Formula URL parameters](https://help.quickbase.com/quickbase-extensions/docs/en/package-builder-url-parameters) - [Use a configuration in batch runs](https://help.quickbase.com/quickbase-extensions/docs/en/batch-config-portal-use) If you have questions, submit a [technical support case](https://help.quickbase.com/docs/get-help-from-quickbase-technical-support).