--- title: "Run a package from a button" slug: "package-builder-run-from-a-button" updated: 2026-10-09T18:17:41Z published: 2026-10-09T18:17:41Z canonical: "help.quickbase.com/package-builder-run-from-a-button" --- > ## 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 from a button The **Process Package** button builds a package for one record while the user watches. It opens a pop-up that runs each step in the sequence and shows its progress, then tells the user when the package is ready or what went wrong. This article explains the button's formula, what the user sees, and where the documents end up. To run packages without a window—automatically, or for many records—see [Run a package in the background](https://help.quickbase.com/quickbase-extensions/docs/en/package-builder-run-in-the-background). ## The button The installation wizard creates the button as the **Process Package (Progress Bar)** field on your master table. It's a **Formula - Text** field with **Allow some HTML tags** turned on: ``` var Text url = "https://..."  // your Package Builder server URL, created by the installation wizard & "request=" & Base64Encode( "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" ); If(Length([Package Builder Template Sequence]) > 0, "Process Package", "Template List not set. Please finish the setup for this Package Builder.") ``` - **The address.** Replace *https://...* with your Package Builder URL, created by the installation wizard—keep the *?* at its end. The parameters are joined with *&* and wrapped in *Base64Encode()* as the single **request** parameter. The field IDs here (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). - **The enhanced security button.** *OpenAsPopup* opens Package Builder in a pop-up sized 1100 × 800, and *POSTTempToken* with *data-temptokendbid* makes Quickbase send a temporary token with the request, so Package Builder can confirm the user has access to the record. *data-temptokendbid* must name the same table as **dbid**—*Dbid()* here. See [Change formula fields](https://help.quickbase.com/quickbase-extensions/docs/en/changing-formula-fields) and [Enhanced security overview](https://help.quickbase.com/quickbase-extensions/docs/en/enhanced-security-overview). - **Refresh.** *data-refresh=true* reloads the record when the pop-up closes, so the user sees the new documents and status. - **No template sequence, no button.** Records whose **Package Builder Template Sequence** is empty show *Template List not set. Please finish the setup for this Package Builder.* instead. - **Merge at the end.** To add an automatic final merge, add *& "&mergeargsfid=60"* (your PDF Merger arguments field ID) inside *Base64Encode()*. See [Merge a package into one PDF](https://help.quickbase.com/quickbase-extensions/docs/en/package-builder-merge-into-one-pdf). - **Details collapsed.** The details table is expanded when the pop-up opens. To start with it collapsed, add *& "&showdetails=false"*. The button doesn't check Package Builder's own batch configuration, so it has no **configid** or **type**. The steps are different: each step runs its extension in batch, even from the button, so each step's arguments are checked against that extension's own batch configuration. 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). Every parameter is explained in [Formula URL parameters](https://help.quickbase.com/quickbase-extensions/docs/en/package-builder-url-parameters). > [!NOTE] > Note > > Package Builder can't be shown inside an iframe—for example in a code page, a web page embedded in a form or dashboard, or another site's frame. The page refuses to load there. Open it in a pop-up, as the wizard's button does, or in a new browser tab. ## What the user sees The pop-up has a blue header, **Package Builder**, and the heading **Generating your Package**. From top to bottom: 1. **Progress bar**—one segment per step in the package, with a percentage complete. The segment of the step that's running is animated blue, finished steps turn green, failed steps turn red, and steps that haven't run yet are grey. 2. **Step description**—the step that's running, such as *Now Generating: Cover Letter (#4)* (template name and Record ID#), or *Now Generating: XL Docs - Template #3* if the template has no name. Below it: *Please do not close this window while the process runs.* 3. **Details** and **Elapsed Time**—select **Details** to show or hide the details table. **Elapsed Time** (minutes:seconds) counts from the start of the package and stops when it finishes or fails. 4. **Details table**—one row per step: | **Column** | **Shows** | | --- | --- | | Status | A color: blue for in progress, green for finished, red for failed, grey for not yet run. | | Template | The template's **Name**, or the extension name plus *Template* if it has none. The automatic final merge from **mergeargsfid** is *Document Merge*. | | Template # | The template's Record ID#, or *N/A* for the automatic final merge. | | Document Type | The **Add-On** value of the template, which is the extension that runs. If it's wrong, change it on the template record. | | Process Time | How long the step took (minutes:seconds). *TBD* until the step finishes. | The steps run one at a time, and the window starts each one. Keep it open until the package finishes. If it's closed, the steps that haven't started don't run. The step that was already running still finishes on our server and creates its document. If that was the last step, or a required step that failed, Package Builder still writes the status field and the Run Details records. Otherwise the status field and Run Details may not be updated for that run. ### When the package is ready The heading changes to **Your package is ready!**, every segment of the bar is green, and the text reads *Successfully processed templates.*, where N is the number of steps that succeeded, including an automatic final merge. A second later it adds *You may now close this window.* ### When a step fails - **A required step fails:** the package stops. The heading changes to **Something went wrong.**, the bar turns red, and the text reads *We've run into an error while generating your package:* followed by the reason, for example *PDF Stamper - Template #3 was required but failed to generate.* (the template's **Add-On** value and Record ID#). For the automatic final merge, the reason is *PDF Merger was required but failed to generate.* The steps after it don't run. To find out why the step failed, 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). - **A not-required step fails:** its row turns red and the package goes on with the next step. When the package finishes, the status field lists the step that failed (see below). - **A step takes longer than 5 minutes:** the window stops waiting for it and shows *Package Builder took too long to respond - please refresh to try again, or contact your app administrator.* If a step regularly takes this long, run the package in the background instead—background runs have no per-step time limit. - **The window sat idle for 20 minutes:** the run's details expire. The next action shows *No Package Details found - your session may have expired. Please refresh the page.* Select the button again to start over. For every message and what to do about it, see [Package Builder messages and troubleshooting](https://help.quickbase.com/quickbase-extensions/docs/en/package-builder-messages). ## Where the results go - **The documents** are wherever each extension's arguments save them—usually file attachment fields on the record, or a repository table, or the extension's cloud storage. Package Builder doesn't move or rename them. If the package has a merge step, the merged PDF is wherever the PDF Merger arguments save it. - **Package Builder Status** (the **stsfid** field) shows the result when the package ends. In these messages, ** is the template's **Add-On** value, such as *XL Docs*: - *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 package stopped. For the automatic final merge, it's *Error Encountered on PDF Merger on *. - **Package Builder Run Details** gets one record per step, with the extension that ran and its process details. See [Run details and status](https://help.quickbase.com/quickbase-extensions/docs/en/package-builder-run-details-and-status). Because the button has *data-refresh=true*, the record reloads with the new documents and status when the user closes the pop-up. ## 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) - [Run a package in the background](https://help.quickbase.com/quickbase-extensions/docs/en/package-builder-run-in-the-background) If something doesn't work as expected, submit a [technical support case](https://help.quickbase.com/docs/get-help-from-quickbase-technical-support).