Overview

The Exact Forms Plus Batch Processor creates documents in the background, without anyone waiting in the browser. It does what the Generate EFP Document buttons do, using the same templates and the same parameters, but it's started by a Quickbase email notification instead of a button.

Use the Batch Processor to:

• Create documents automatically when a record changes, for example when an order's status becomes Approved, with no button to select. This works for records changed one at a time, with Grid Edit, or by an import.

• Create many documents in one run from a report or query, for example invoices for every open order, optionally merged into one file.

How it works

1. Something changes on a record: a user selects the Execute EFP Batch or Execute Batch button, or a field you chose changes.

2. A Quickbase email notification on that table sends the record's Batch Processing Arguments to the Batch Processor's email address.

3. The Batch Processor reads the arguments, checks them against your app's batch configuration, gets the records, and creates the documents, the same way the buttons do.

4. It saves each document where the arguments say (a file attachment field, cloud storage, or a repository table), and writes the result back to the record: PROCESS COMPLETED_ with the date and time, or ERROR ENCOUNTERED_ with the error.

You don't need to keep the record open while the run is processed.

Batch Processor or buttons?

Templates, embedded reports, functions, file names, saving options, protection, and merging all work the same in both. Test mode (test=y) is available only on the buttons.

Two kinds of setup

The installation wizard sets up the Batch Processor for you. On the Exact Forms Plus setup type step, choose one of these:

Single document generation (automatic documents)

Creates a document for one record at a time, on the record itself. The wizard adds these fields to the master table, next to the regular buttons:

• Batch Processing Arguments: the formula with the arguments for the record.

• EFP Batch Trigger - Msg Field: the status field. It shows Batch Execution Requested_ and the time while a run is waiting, then the result.

• Execute EFP Batch: a button that requests a run for the record by setting the status field. It's hidden while a run is waiting.

• Exact Forms Plus Batch Email: the Batch Processor's email address, for the notification.

To create documents automatically, set up the email notification to fire on the change you want, for example when Status changes to Approved. To let users request a document, have it fire when EFP Batch Trigger - Msg Field changes and contains Requested.

Bulk document generation (many documents)

Creates documents for every record returned by a report or query on the master table, started from a control record. The wizard adds three tables:

A user selects Execute Batch on a Batch Processing record. While the run is waiting, the record shows a processing message; select Refresh until it shows the result. Each document is saved to its own master record (or where the arguments say), and if merging was chosen, all the documents are combined into one PDF in Merged File on the Batch Processing record.

Don't rename the Logs fields; the Batch Processor writes them by name.

Set up the email notification

The wizard doesn't create the email notification that starts each run. Create it on the master table (single setup) or the Batch Processing table (bulk setup). For the settings, the custom message, and when to notify, see Email notification setup.

Check the result

• On the record: the status field shows PROCESS COMPLETED_ and the time when the run succeeds, or ERROR ENCOUNTERED_, the time, and the error. The time is in your app's time zone.

• In a bulk setup: the Batch Processing Logs record shows how many documents were created and when the run started and ended. Any errors are in Batch Processing Errors, with the arguments that were used.

• If the status field still shows Batch Execution Requested_ long after the run should have finished, check the notification and the arguments. See If nothing happens and If the batch run doesn't work.

Change the arguments

You can change the Batch Processing Arguments formula at any time, for example to use another template, save the documents to another field, or process other records. Your batch setup is in two places, though, and both must agree:

• The Batch Processing Arguments formula field in your Quickbase app, which says what to do.

• Your app's Exact Forms Plus batch configuration in the Batch Configuration Portal, which lists the parameters and values the Batch Processor is allowed to run with. The configid parameter points the Batch Processor to it. The installation wizard creates it for you.

If your account requires batch configurations, the Batch Processor compares each argument with the batch configuration. When a parameter is listed in the batch configuration, its value must be one of the parameter's allowed values, exactly, including upper and lower case. If it isn't, no documents are created. Parameters that aren't listed in the batch configuration aren't checked. So whenever you change the formula, make sure the batch configuration also has the changed parameters and values.

Edit the formula and the batch configuration

1. In your Quickbase app, edit the Batch Processing Arguments field's formula, following the rules in How the arguments are written. Don't remove configid or type.

2. Open a record and copy the value the field shows (the formula's result, not the formula). You'll compare it with the batch configuration.

3. In the Extensions Portal, open the Batch Configuration Portal.

4. On Batch Add-Ons, select Go To Configs on the Exact Forms Plus row. Find the configuration whose Config Key ends with the same characters as the configid= value you copied, and select Go To Values.

5. On the Configured Parameters screen, check each parameter you changed:

   • The parameter is listed: select Modify, enter the new value (or add it as another allowed value with +), and select Save.

   • You added a parameter you want to lock down: select Add New, enter the parameter name and its allowed values, and select Save.

   • You removed a parameter from the formula: nothing is checked for a parameter the run doesn't send, so you can leave it. To remove it from the batch configuration, open a technical support case.

6. Start a run on a test record and check the status field.

Changes to the batch configuration apply to the next run. You don't need to change the email notification.

Note: A parameter can have up to 10 allowed values. Only lock parameters whose value is the same for every record, or one of a few values. A value that changes from record to record, such as msid built from [Record ID#], can't match a fixed list, so leave that parameter out of the batch configuration.

If the arguments don't match

No documents are created, and the status field (and in a bulk setup, the Errors table) shows ERROR ENCOUNTERED_, the time, and one of these messages:

For more, see Create and manage batch configurations.

Limits and security

• Your account sets the maximum number of documents per batch run and the maximum records per embedded report. Records past the document limit are skipped; see Limits.

• An error stops the run. Documents created before the error are kept.

• The batch configuration means a changed formula can't save documents somewhere you didn't approve. See Change the arguments.

Next: Email notification setup. See also: Exact Forms Plus Batch Processor parameters, Set up Exact Forms Plus with the installation wizard.