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.
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,
"<a class='Vibrant Success OpenAsPopup POSTTempToken' data-height=800 data-width=1100 data-refresh=true data-temptokendbid='" & Dbid() & "' href=\"" & $url & "\">Process Package</a>",
"<b>Template List not set. Please finish the setup for this Package Builder.</b>")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.
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 and 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.
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. Every parameter is explained in Formula URL parameters.
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:
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.
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.
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.
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 <N> 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.
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.
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, <Add-on> is the template's Add-On value, such as XL Docs:
Process Successfully Completed on <date and time>—every required step worked. If a not-required step failed, a line is added for it: Error Encountered on <Add-on> - Template # <Record ID#>.
Error Encountered on <Add-on> - Template # <Record ID#> on <date and time>—a required step failed and the package stopped. For the automatic final merge, it's Error Encountered on PDF Merger on <date and time>.
Package Builder Run Details gets one record per step, with the extension that ran and its process details. See 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
If something doesn't work as expected, submit a technical support case.