Set up a package

A package is a set of documents Package Builder creates for one record, by running other Quickbase Extensions one after another: Exact Forms Plus, XL Docs, PDF Stamper, and PDF Merger. Each extension creates its document the way it already does on its own, using its own batch arguments. Package Builder decides which extensions run, with which arguments, and in what order.

Setting up a package has two parts. The installation wizard adds the fields and tables Package Builder needs. Then you tell it what goes in the package: which templates, which arguments, and the sequence. This article covers both.

Before you start

• Set up each extension on its own first. Package Builder doesn't create documents itself. Every extension you want in the package must be installed and working in batch on the same table, with a batch arguments field that creates the right document for a record. See Exact Forms Plus, XL Docs (and its Batch processing article), and PDF Stamper.

• Use each extension's single-record setup. Package Builder reads each step's arguments from a field on the master record, so each extension must be set up for single-record generation on the master table. That setup creates these arguments fields on the table you choose:

  Extension	Arguments field its installation wizard creates
  Exact Forms Plus	Batch Processing Arguments
  XL Docs	XL Docs Batch Processing Arguments
  PDF Stamper	PDF Stamper Batch Processing Arguments
  PDF Merger	PDF Merger Parameters

  A bulk setup (many records at once) keeps its arguments on a separate Batch Processing table instead of on the master record, and Package Builder can't read them there.

• You need a Document Templates table. Exact Forms Plus, XL Docs, and PDF Stamper create one when you install them. Without it, the Package Builder wizard stops with This application does not currently have any of our Document Generation add-ons installed. Please install one of our Document Generation add-ons before attempting to install Package Builder.

• PDF Merger is only needed for one merged PDF. If you just want the separate documents, you can skip it. To combine them, set up PDF Merger and see Merge a package into one PDF.

Run the installation wizard

Open the wizard from the Extensions Portal: select Setup on the Package Builder tile. See Quickbase Extensions installation wizard overview.

The wizard has one Package Builder step: choose the table under Select Table to Setup and check I understand the above message. Choose the table you'll run packages from—the master table. It's usually the table where your extensions' batch arguments fields already are, because each step reads its arguments from a field on this table. See Package Builder Setup and Package Builder Finish.

As the wizard's finish page says, the setup isn't done when the wizard closes. You still need to add your templates and set the sequence, as described in After the wizard.

What the wizard creates

Fields on the Document Templates table

The wizard uses your existing Document Templates table (or creates one) and adds three fields. Each template record that's part of a package is one step.

Package Builder also reads the template's Name and shows it in the progress window. It finds these fields by their labels, so don't rename Name, Add-On, Arguments FID, or Not Required in Package.

Fields on the master table

Unlike the installation wizards of Exact Forms Plus or XL Docs, the Package Builder wizard doesn't create a trigger field, an Execute button, or the email notification for background runs. You choose what starts a background run and create the notification yourself; see Run a package in the background.

The formula of Package Builder Template Sequence as the wizard creates it (the comment line may differ):

// Period-delimited list of Document Template Record ID#s, in run order
""

The formula of Package Builder Batch Arguments. 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.

"clientid=Q1234"  // your Client ID
& " appid=" & AppID()
& " dbid=" & Dbid()
& " msid=" & [Record ID#]
& " tpdbid=" & [_DBID_DOCUMENT_TEMPLATES]
& " apptoken="
// Package Builder parameters
& " pckgsq=" & [Package Builder Template Sequence]  // period-delimited list of template Record ID#s, in run order
& " stsfid=51"  // Package Builder Status
& " rddbid=" & [_DBID_PACKAGE_BUILDER_RUN_DETAILS]  // Run Details table
& " rdrelfid=6"  // Run Details: Related <master table>
& " rdadnfid=8"  // Run Details: Addon ran
& " rdntsfid=7"  // Run Details: Process Details
& " configid=<your Config Key>"  // the batch configuration the wizard created
& " type=packagebuilder"  // packagebuildereu for EU accounts

The formula of Process Package (Progress Bar):

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="
// Package Builder parameters
& "&pckgsq=" & [Package Builder Template Sequence]
& "&stsfid=51"
& "&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>")

Every parameter is explained in Formula URL parameters.

The Package Builder Run Details table

The wizard creates a Package Builder Run Details table, related to the master table. Each run adds one record per step:

Process Details contains the step's full arguments, including any application token in them. Limit access to this table to the roles that need it. See Run details and status.

A batch configuration

The wizard also creates a batch configuration for Package Builder in the Batch Configuration Portal, with clientid and appid pinned to your Client ID and this app, and adds its key to Package Builder Batch Arguments as configid. Background runs need it; button runs don't use it. See Run a package in the background.

This configuration covers only Package Builder's own arguments. Each step is also checked against its own extension's configuration, from the button and in the background. See Each step's own batch configuration.

After the wizard

Step 1. Choose the templates for the package

Each step in a package is a record in the Document Templates table. Decide which documents go in the package, and note each template's Record ID#—the sequence is built from them.

• For Exact Forms Plus, XL Docs, and PDF Stamper, use the template records those extensions already use.

• For a PDF Merger step, add a template record just for the step, for example named Package PDF Merge. It doesn't need a template file. See Merge a package into one PDF.

• To see Record ID#s, open the Document Templates table and add the Record ID# column to the report, or open a template record.

Step 2. Set each template's Add-On and Arguments FID

1. Find the arguments field's ID. In your app, select ... (more options) next to the master table in the left bar, then select Fields. Search for the extension's arguments field—Batch Processing Arguments (Exact Forms Plus), XL Docs Batch Processing Arguments, PDF Stamper Batch Processing Arguments, or PDF Merger Parameters—and note the number in the Field ID column.

2. Edit the template record. Open the Document Templates table and select the edit (pencil) icon next to the template.

3. Choose the Add-On. In Add-On, choose the extension that creates this document:

   Add-On	Use it for
   Exact Forms Plus	Word documents and PDFs created from a Word template.
   XL Docs	Excel workbooks, CSV files, and PDFs created from an Excel template.
   PDF Stamper	PDFs created by stamping data onto a PDF template.
   PDF Merger	Combining PDFs into one document.

4. Enter the Arguments FID: the field ID from step 1.

5. Decide whether the step is required. Leave Not Required in Package unchecked if the package can't go on without this document. Check it for optional documents.

6. Save, and repeat for each template in the package.

When you're done, the templates for the package might look like this:

The Add-On list in some apps also shows Static Document and Dynamic Document. Those steps only work in repository mode, which you set up by hand. See Repository mode.

Step 3. Write each arguments field

Each step runs its extension with the value of the field named in Arguments FID, on the record the package is built for. Write that field exactly as you would for the extension's own batch processing:

• Use the extension's batch arguments—parameters separated by spaces, for one record (msid= the Record ID#). Package Builder passes the field to the extension as it is.

• Include that extension's Config Key. Every run of the extension needs configid=<that extension's Config Key>, and the run's other values must be allowed by that configuration. The extension's installation wizard adds configid= to the field it creates. See Each step's own batch configuration.

• Say where the document goes. Package Builder doesn't move or rename the documents; each extension saves its document where its arguments tell it to, usually a file attachment field on the master record. A merge step later reads the documents from those fields.

• One run per line (regular mode). In regular mode, a step can run its extension more than once. Put each run's arguments on its own line, separated by a line break ("\n" in a formula). Package Builder runs the lines in order, one at a time. Don't leave blank lines. In repository mode, the whole field is passed to the extension in a single run instead.

• Test each field on its own first. If the extension's batch run doesn't create the document from these arguments, the step won't either.

For example, an XL Docs arguments field that creates two PDFs—the schedule and a cost summary—in one step. Field 55 is XL Docs Document, the field the XL Docs installation wizard created, so its configuration already allows it. Field 56 (Cost Summary PDF) is a field you added, so add 56 to the allowed values of faid in the XL Docs configuration first. The field IDs and template IDs are examples:

"clientid=Q1234 appid=" & AppID() & " dbid=" & Dbid() & " msid=" & [Record ID#]
& " tpdbid=" & [_DBID_DOCUMENT_TEMPLATES] & " tpid=3 docfmt=pdf fn=Schedule faid=55"
& " configid=<your XL Docs Config Key>"
& "\n"
& "clientid=Q1234 appid=" & AppID() & " dbid=" & Dbid() & " msid=" & [Record ID#]
& " tpdbid=" & [_DBID_DOCUMENT_TEMPLATES] & " tpid=5 docfmt=pdf fn=Costs faid=56"
& " configid=<your XL Docs Config Key>"

For each extension's parameters, see its own batch processing articles.

Each step's own batch configuration

Batch configuration checking is on for every account. Each step runs its extension in batch—from the Process Package button as well as in the background—so that extension checks the step's arguments against its own batch configuration, separately from Package Builder's:

• Include the extension's Config Key. Each arguments line needs configid=<that extension's Config Key>. The extension's installation wizard adds it to the field it creates; keep it, and add it to every line you write yourself. Without it, the extension stops without creating the document.

• Match its allowed values. Every parameter that the extension's configuration lists must match one of its allowed values exactly. The configurations that the Exact Forms Plus, XL Docs, and PDF Stamper wizards create allow:

  • in faid, only the file attachment field that wizard created (EFP Document, XL Docs Document, or PDF Stamped Document)

  • in the merge options mrgdbid, mrgfa, and mrgkeyfid, only an empty value

  • in the repository options rpdbid and rpfafid, only the repository table you chose in that wizard—or, if you didn't choose one, only an empty value

  The configuration the PDF Merger wizard creates checks only clientid and appid.

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

To find a configuration and change its allowed values, see Create and manage batch configurations. For how values are checked, see Use a configuration in batch runs.

Step 4. Set the sequence

Open the master table's fields (... next to the table, then Fields), select Package Builder Template Sequence, and set its formula to the template Record ID#s in the order you want them to run, separated by periods.

• The sequence is the run order. Package Builder runs the steps exactly in this order, one at a time. A step that uses another step's document—such as a PDF Merger step—must come after it.

• The page order inside a merged PDF is set by PDF Merger's own arguments, not by the sequence. See Merge a package into one PDF.

• Optional steps: add :u (or :U) after a Record ID# to make that step not required, for example 4.3:u.7. It works the same as checking Not Required in Package on the template; use the checkbox when the template is optional in every package, and :u when it's optional in just this one.

• Required steps: if a required step fails, the package stops and the rest of the steps don't run. If a not-required step fails, the package keeps going and the status field lists the step that failed.

• The sequence is a formula, so it can change per record. For example, include the schedule only for projects that have one:

// Cover Letter = 4, Project Schedule = 3, Package PDF Merge = 7
If([Has Schedule], "4.3.7", "4.7")

After you save the sequence, the Process Package button appears on records where the sequence has a value.

Worked example: a project package

A Projects table needs one PDF per project that combines a cover letter and a project schedule. Exact Forms Plus and XL Docs are already set up on Projects for single-record generation, and PDF Merger is installed.

1. The documents. On Projects, three file attachment fields hold the output: EFP Document (field 45, created by the Exact Forms Plus wizard) for the cover letter, XL Docs Document (field 55, created by the XL Docs wizard) for the schedule, and Project Package (field 61) for the merged PDF. Because 45 and 55 are the wizards' own output fields, their batch configurations already allow them.

2. The arguments fields. On Projects:

   • Batch Processing Arguments (field 40), the arguments field the Exact Forms Plus installation wizard creates: Exact Forms Plus arguments that create the cover letter from template 4 as a PDF and save it in field 45, with the Exact Forms Plus configid=.

   • XL Docs Batch Processing Arguments (field 54): XL Docs arguments that create the schedule from template 3 as a PDF and save it in field 55, with the XL Docs configid=.

   • PDF Merger Parameters (field 60): PDF Merger arguments that merge fields 45 and 55 on the record, in that order, into field 61, with the PDF Merger configid=.

3. The templates. In Document Templates:

   Record ID#	Name	Add-On	Arguments FID	Not Required in Package
   4	Cover Letter	Exact Forms Plus	40	unchecked
   3	Project Schedule	XL Docs	54	unchecked
   7	Package PDF Merge	PDF Merger	60	unchecked

4. The sequence. Some sample values for Package Builder Template Sequence:

   pckgsq	What happens
   4.3.7	Cover letter, then schedule, then the merge. If any step fails, the package stops there.
   4.3:u.7	The same, but if the schedule fails, the package goes on to the merge and the status field notes the failed schedule.
   4.3	Creates the cover letter and schedule as separate PDFs, with no merge.
   3.4.7	Creates the schedule first. The merged PDF's page order doesn't change, because PDF Merger's arguments list field 45 before field 55.

5. Run it. Select Process Package on a project. The pop-up shows three steps—Cover Letter, Project Schedule, Package PDF Merge—and when they finish, Your package is ready! The record shows the two PDFs and the merged Project Package, and Package Builder Status reads Process Successfully Completed on the date and time.

Instead of the Package PDF Merge template, you could add mergeargsfid=60 to the button and batch arguments and use the sequence 4.3; Package Builder then adds the merge as a final step on its own. See Merge a package into one PDF.

Next steps

• Run a package from a button

• Run a package in the background

• Merge a package into one PDF

• Package Builder messages and troubleshooting

If you have questions about setting up a package, submit a technical support case.