Repository mode

Repository mode builds a package in a separate repository table: a child table related to your master table. Each step in the sequence adds its document to that table as a new record, related to the master record. A PDF Merger step at the end then merges those records into one PDF. Repository mode is also the only mode that can add files that no extension generates, using Static Document and Dynamic Document steps.

Note

Repository mode is an advanced setup that you build by hand. The installation wizard doesn't create a repository table, doesn't add the repository parameters to the Package Builder fields, and doesn't offer Static Document or Dynamic Document in the Add-On field. Set up a package in regular mode first (see Set up a package), then use this article to switch it to repository mode.

When to use repository mode

• Keep every document of the package. Each document is its own record in one table, so users can open, review, or download the parts as well as the merged PDF.

• Add fixed files. Cover letters, terms and conditions, or a "This page intentionally left blank" page, added with a Static Document step.

• Add files from the record. A signed agreement or a form a user uploaded to the master record, added with a Dynamic Document step.

• Merge from one place, in order. Because every part of the package is in one table, a single PDF Merger query can collect them, sorted in the order they were added.

How repository mode works

1. Clear old records. Before the run, Package Builder deletes the repository records related to this master record, so the package starts empty. You can change or turn off this cleanup with rppurgemode and rpaqry. See Clearing old records.

2. Run each step in order. Package Builder runs the steps in the order of the Record ID#s in pckgsq, and waits for each one to finish before starting the next.

   • Exact Forms Plus, XL Docs, and PDF Stamper steps save their document to the repository table themselves, using repository options in their own arguments.

   • Static Document and Dynamic Document steps are handled by Package Builder: it copies the file and adds it to the repository table as a new record.

3. Merge. A PDF Merger step, normally the last one, finds the repository records for this master record, sorts them by Record ID#, and merges them into one PDF. The merged PDF goes wherever the PDF Merger arguments say, for example a file attachment field on the master record.

Set up the repository table

Create a table to hold the parts of each package, for example Package Documents, and relate it to your master table, so that one master record has many package documents. The table needs these fields:

To create the table:

1. In your app, create the table and add the file attachment field.

2. Create a relationship where one master record (for example one Project) has many repository records. Quickbase adds the reference field to the repository table.

3. Open the repository table's Fields settings and note the field IDs of the reference field and the file attachment field. Note the table alias too, for example [_DBID_PACKAGE_DOCUMENTS], and the table ID. See Find your Client ID, table IDs, and field IDs.

Repository mode parameters

Add these parameters to the two Package Builder fields on the master table: Process Package (Progress Bar) for runs from the button, and Package Builder Batch Arguments for runs in the background. In the button formula, each parameter starts with &; in the batch arguments, each starts with a space. The full list of Package Builder parameters is in Formula URL parameters.

If rpmode is on and rpdbid, rprelfid, or rpfafid is missing, nothing is built. From the button, the window shows The parameters are invalid. Please contact your app administrator.

Package Builder's own batch configuration, as the wizard creates it, checks only clientid and appid, so adding these parameters to Package Builder Batch Arguments doesn't need a change there. The steps' own configurations are different; see Each step's own batch configuration.

Clearing old records

Warning

By default, repository mode deletes records. Before each run, Package Builder deletes every record in the repository table that is related to the master record, including files that users added by hand and documents from earlier runs. Package Builder doesn't keep a copy of what it deletes. If the repository table holds anything you want to keep, set rpaqry to protect those records, or set rppurgemode=none, before you run the package.

Package Builder finds the records to delete with the query {'rprelfid'.EX.'rpkeyval'} (the master record's Record ID# if you don't set rpkeyval). When rpaqry is set, it's added with AND, so only related records that also match rpaqry are deleted.

Static Document and Dynamic Document steps

These two step types add a file that no extension generates. They work only in repository mode. Don't put them in a package that runs in regular mode.

To use them:

1. In the Document Templates table, open the settings of the Add-On field and add the choices Static Document and Dynamic Document. Type them exactly like this, with the same capitals; Package Builder matches the Add-On value exactly.

2. Add a template record for each file, choose the Add-On value, and set it up as in the table above.

3. Add the template's Record ID# to the master record's Package Builder Template Sequence at the position where the file belongs in the package.

When the step runs, Package Builder downloads the file and adds a new record to the repository table: the master record's key goes in rprelfid and the file goes in rpfafid. The file name starts with the file's position in the package. These file types keep their extension: .pdf, .doc, .docx, .xls, .xlsx, .jpg, .jpeg, .png, .gif, .bmp, .tif, and .tiff. If you plan to merge the package into one PDF, PDF files are the safest choice.

If the field for a Dynamic Document is empty on a record, the step fails. Mark the step as not required (add :u after its Record ID# in the sequence, or check Not Required in Package on the template) if the package should be built without it.

Where each step's output goes

A few things to know:

• Two different rpmode parameters. The extensions have their own repository parameters with similar names. XL Docs, for example, turns its repository output on with repository=y and has an rpmode of its own (a to add a record, u to update one), along with rpdbid, rpfid, and rpfafid. Package Builder's rpmode=y goes in the Package Builder fields; the extension's repository=y and rpmode=a go in that extension's arguments field. Use the extension's add option so each run adds a new record.

• One run per step. In repository mode, each step runs its extension once, with the whole arguments field. Unlike regular mode, the field isn't split into lines.

• Order. Steps run one at a time in sequence order, so their records are added in that order. Sort the merge by Record ID# (slist=3 in PDF Merger) to get the package order.

• Merging. Add the PDF Merger step as the last template in the sequence, or set mergeargsfid to the PDF Merger arguments field so Package Builder adds a merge step at the end for you. See Merge a package into one PDF.

Each step's own batch configuration

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

• Each step's arguments must include configid=<that extension's Config Key>.

• The configurations that the Exact Forms Plus, XL Docs, and PDF Stamper wizards create allow, in rpdbid and rpfafid, only the repository table you chose in that wizard—or only an empty value if you didn't choose one. They allow only the wizard's own output field in faid.

• So before you add repository options for a new repository table, such as Package Documents, add that table's ID to rpdbid and its file attachment field ID to rpfafid in that extension's configuration in the Batch Config Portal. Otherwise the step fails, or its document isn't created.

• The configuration the PDF Merger wizard creates checks only clientid and appid, so the merge query below doesn't need a change there.

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

Example: a project invoice package

Each project needs one PDF made of a cover letter, the invoice, and the signed contract, in that order. Users should also be able to open each part on its own.

Tables and fields

• Projects (master table). Fields used: XL Docs Batch Processing Arguments (field 54, the invoice), Signed Contract (file attachment, field 60), PDF Merger Parameters (formula text, field 61), Project Package (file attachment, field 62, receives the merged PDF), Package Date (date/time, field 63), and the fields the installation wizard added.

• Package Documents (repository table, alias [_DBID_PACKAGE_DOCUMENTS]). Fields: Related Project (reference field, field 6), Document (file attachment, field 7), Keep (checkbox, field 8).

Document Templates records

The project's Package Builder Template Sequence is 7.3.8.9. The signed contract is optional, so a project without one still gets a package.

Formulas

First, in the Batch Config Portal, open the XL Docs configuration whose key is in XL Docs Batch Processing Arguments, and add the Package Documents table ID to rpdbid and 7 to rpfafid.

Then, in XL Docs Batch Processing Arguments (field 54), keep the invoice's arguments, including its configid=, and add XL Docs's repository options so the invoice is saved as a new Package Documents record:

... // the invoice's existing XL Docs arguments, including configid=<your XL Docs Config Key>
& " docfmt=pdf"
& " repository=y"  // XL Docs: save to a repository table
& " rpdbid=" & [_DBID_PACKAGE_DOCUMENTS]
& " rpfid=6"      // Related Project
& " rpfafid=7"    // Document
& " rpmode=a"     // XL Docs: add a new record

In PDF Merger Parameters (field 61), merge this project's Package Documents records, sorted by Record ID#, into Project Package on the project:

"clientid=Q1234"  // your Client ID
& " appid=" & AppID()
& " dbid=" & [_DBID_PACKAGE_DOCUMENTS]
& " msqry={'6'.EX.'" & [Record ID#] & "'}"
& " clist=3.7"
& " slist=3"
& " mrgdbid=" & Dbid()
& " mrgrid=" & [Record ID#]
& " mrgfa=62"
& " mrgfn=Project_Package_" & [Record ID#]
& " mrgdte=63"
& " configid=<your PDF Merger Config Key>"
// keep any other parameters the PDF Merger installation wizard added

In Process Package (Progress Bar), add these lines inside Base64Encode( ... ), after the pckgsq line:

& "&rpmode=y"
& "&rpdbid=" & [_DBID_PACKAGE_DOCUMENTS]
& "&rprelfid=6"
& "&rpfafid=7"
& "&rpaqry={'8'.EX.'0'}"   // keep records with Keep checked

In Package Builder Batch Arguments, add the same parameters, each starting with a space:

& " rpmode=y"
& " rpdbid=" & [_DBID_PACKAGE_DOCUMENTS]
& " rprelfid=6"
& " rpfafid=7"
& " rpaqry={'8'.EX.'0'}"

What happens when it runs

1. Package Builder deletes the project's Package Documents records that don't have Keep checked.

2. Cover Letter (template 7): Package Builder copies Cover Letter.pdf into a new Package Documents record.

3. Invoice (template 3): XL Docs creates the invoice PDF and adds it as the next record.

4. Signed Contract (template 8): Package Builder copies the file in the project's Signed Contract field into the next record. If the field is empty, the step fails, and because it's not required, the run continues.

5. Package PDF Merge (template 9): PDF Merger merges the project's Package Documents records in Record ID# order and saves the merged PDF in the project's Project Package field.

6. Package Builder writes Process Successfully Completed on and the date and time to Package Builder Status. See Run details and status.

Afterwards, Package Documents holds these records for project 25:

The next run of the package for project 25 deletes these three records first and adds new ones.

Related articles

• Set up a package

• Merge a package into one PDF

• Formula URL parameters

• Package Builder messages and troubleshooting