Batch processing

Batch processing runs XL Docs in the background, with no window for the user to wait on. A Quickbase email notification sends the processing arguments to the XL Docs batch processor, which creates the documents, saves them on your records, and writes its status back to a field on the record that started the run.

Use batch processing to:

• Create documents in bulk—more than a single button click can create (up to 50 by default; your account's limit may differ; see Generate documents for multiple records).

• Create documents automatically when something happens to a record—for example, when a record is saved, when several records are changed with grid edit, or when records are imported—so nobody has to click a button.

The batch processor works like the web version of XL Docs and accepts the same parameters (see Formula URL parameters), so a template that works from a button works in batch too.

How it works

1. Something changes on the record—a user clicks the Execute Batch button, or another change you choose happens—and the trigger field is updated to contain Requested (the button writes Batch Execution Requested_ followed by the date and time).

2. A Quickbase email notification on that table fires and sends the XL Docs Batch Processing Arguments field to the XL Docs batch address.

3. The batch processor reads the arguments, finds the records in msqry (or the single record in msid), and creates and saves the documents.

4. When it's done, it updates the trigger field (the field in xldbtfld) on the record in xldbrid: PROCESS COMPLETED_ followed by the date and time, or the error message if something went wrong. If you use a log table (logsdbid), it also adds a log record. For a single-record run you can use triggerfid instead (see Status on the record (triggerfid)).

Typical example

To create documents in bulk, an app usually has a control table: a record high up in the relationships—a Projects record, for example—that drives the creation of documents for records in a child table. For one Project you might want an expense statement for every employee on the project. With up to 50 employees, a button can do this (see Generate documents for multiple records). With more than 50, use the batch processor.

What the installation wizard installs

The installation wizard installs everything batch processing needs. What you get depends on the setup type you choose (see XL Docs setup type).

Single document generation setup

The wizard adds these batch fields to the table you selected, next to the buttons that create documents from a click. Use them to create a record's document automatically when the record changes.

Bulk document generation setup

The wizard creates two tables:

• XL Docs Batch Processing—the control table. You start a batch run from a record in this table.

• XL Docs Batch Processing Logs—one record per run, with what happened: the start and end time, the number of documents processed, and any errors.

The XL Docs Batch Processing table has these fields:

If you chose Amazon S3 storage, the wizard also adds S3 Key and View File fields (see Output and storage).

The XL Docs Batch Processing Logs table has these fields: Related Batch Processing, XL Docs Batch Processing - Name (a lookup of the run's name), Status, Notes, Documents Processed, Start, End, and Run Duration (a Formula - Duration field: End minus Start). See Status messages for what each run writes.

After the wizard finishes, there is one more step: create the email notification. The wizard's finish page reminds you: Your setup for generating documents automatically is not finished!

Batch processing arguments

The XL Docs Batch Processing Arguments formula uses the same parameters as a button (see Formula URL parameters), with these differences:

• There is no base address—no server URL and no page name.

• Parameters are separated by spaces instead of &. Don't put spaces anywhere else—write tpid=3, not tpid = 3.

• If a value contains spaces or special characters, wrap it in escaped double quotes: fn=\"XLD Bulk Document\", msqry=\"({'43'.GT.'0'})\".

• type tells the batch processor which extension the request is for. For XL Docs it is xldocsbatch, or xldocsbatcheu if your account is hosted in the EU. The installation wizard sets the right value; it must match the batch address the email notification sends to.

• xldbdbid, xldbrid, and xldbtfld tell the batch processor where to write its status: the table, the record, and the trigger field. Set all three if you want to see when the run is done or why it failed.

• triggerfid (optional, single-record runs only) is the field ID of a text field on the record being processed, where the run's status is written. See Status on the record (triggerfid).

• logsdbid (optional) is the XL Docs Batch Processing Logs table, where a record is added for each run.

• Keep the configid value the installation wizard created. The batch processor always checks the arguments against that batch configuration. See Batch configurations and Use a configuration in batch runs.

Example: bulk documents from a control record

"clientid=Q#"  // your Client ID
& " appid=" & AppID()
& " dbid=" & [_DBID_PROJECT_EMPLOYEES]  // the table to create documents for
& " tpdbid=" & [_DBID_DOCUMENT_TEMPLATES]
& " tpid=3"
& " fn=\"XLD Bulk Document\""
& " msqry=\"({'43'.GT.'0'})\""
& " faid=39"
& " xlddte=40"
& " docfmt=xlsx"
& " apptoken="  // add your app token after = if your app requires application tokens
& " logsdbid=" & [_DBID_XL_DOCS_BATCH_PROCESSING_LOGS]
& " xldbdbid=" & Dbid()
& " xldbrid=" & [Record ID#]
& " xldbtfld=7"  // the Trigger Field
& " type=xldocsbatch"  // xldocsbatcheu if your account is hosted in the EU
& " configid=..."  // keep the value created by the installation wizard

Replace Q# and the table, field, and record IDs with your own (see Find your Client ID, table IDs, and field IDs).

To use a report instead of a query, replace msqry with msqid= and the report ID. To merge all the documents into one PDF on the control record, set docfmt=pdf and add mrgdbid, mrgrid, mrgfa and, optionally, mrgfn and mrgdte, as described in Merge all documents into one PDF.

Example: one document when a record changes

To create a single record's document automatically, use msid for the record itself:

"clientid=Q#"
& " appid=" & AppID()
& " dbid=" & Dbid()
& " tpdbid=" & [_DBID_DOCUMENT_TEMPLATES]
& " tpid=1"
& " msid=" & [Record ID#]
& " fn=XLDBDocument"
& " faid=51"
& " xlddte=52"
& " docfmt=pdf"
& " apptoken="
& " xldbdbid=" & Dbid()
& " xldbrid=" & [Record ID#]
& " xldbtfld=53"  // the XL Docs Batch Trigger Field
& " type=xldocsbatch"  // xldocsbatcheu if your account is hosted in the EU
& " configid=..."

Status on the record (triggerfid)

For a single-record run (dbid plus msid), you can have the batch processor write its status into a text field on that same record by adding triggerfid with the field's ID. Multi-record runs (msqry or msqid) use xldbdbid, xldbrid, and xldbtfld on the control record instead.

• When the run starts, the field is set to PROCESSING_ followed by the date and time.

• When the run ends, it is set to PROCESS COMPLETED_ followed by the date and time, or to the error message if the run failed—the same wording as xldbtfld.

• If the status can't be written (for example, the field ID is wrong), the document is still created.

The installation wizard doesn't add triggerfid. To see the status in the wizard's XL Docs Batch Trigger Field, add triggerfid= and that field's ID to the XL Docs Batch Processing Arguments formula:

& " triggerfid=8"  // the XL Docs Batch Trigger Field's ID

Execute Batch button

The installation wizard creates this button for you (Execute Batch on the XL Docs Batch Processing table, or Execute XL Docs Batch on your table). It's a Formula - URL field that uses the Quickbase API to write Batch Execution Requested_ and the current time into the trigger field, then returns to the record. While a run is requested, the button is hidden, so users don't start it twice.

If(Contains([Trigger Field], "Requested"), "",
  URLRoot() & "db/" & Dbid() & "?"
  & "act=API_EditRecord"
  & "&rid=" & URLEncode([Record ID#])
  & "&_fid_7=Batch Execution Requested_" & ToText(Now())  // 7 = your Trigger Field
  & "&apptoken=[Your App Token]"
  & "&rdr=" & URLEncode(URLRoot() & "db/" & Dbid() & "?"
  & "a=dr"
  & "&rid=" & URLEncode([Record ID#]))
)

Replace [Your App Token] with an application token from your app's settings, or remove that line if your app doesn't require application tokens. Never publish a real token in shared formulas or documentation.

You don't need the button if documents should be created when something else happens. Any change that writes Requested into the trigger field—a form rule, an automation, a grid edit, or an import—starts a run.

Create the email notification

The email notification is what actually sends the request to the batch processor. Create it on the table that holds the trigger field and the arguments field (for a bulk setup, the XL Docs Batch Processing table).

1. Open the table's ⋯ menu, select Notifications, subscriptions & reminders, then select + New Email and choose Notification.

2. Set Permission type to Open: Emails sent openly to anyone.

3. Give the notification a meaningful name, for example XL Docs Batch Processing.

4. In Notify whom, enter xldocsbatch@xldocsbatch.quickbasetools.com. If your account is hosted in the EU, use xldocsbatcheu@xldocsbatch.quickbasetools.com (with type=xldocsbatcheu in the arguments). You can add other addresses if you want people to be told when someone requests a run.

5. Under Notification when, choose the first option: a record is modified (the option shows your table's record name, for example an XL Docs Batch Processing is modified).

6. Open Additional criteria, choose Any of the following fields change, and select the trigger field (Trigger Field or XL Docs Batch Trigger Field).

7. Under the conditions that must be true after the change, choose all of these conditions are true and add: the trigger field contains the value Requested.

8. Set Message type to Custom message, and enter a descriptive Subject, for example XL Docs Batch Request.

9. In the custom message box, insert only the XL Docs Batch Processing Arguments field—pick it from the list of fields beside the message box. Don't add any other text to the message.

10. Select Save.

Note

The contains Requested condition is required. The batch processor writes its status into the trigger field when it finishes; without the condition, that update would fire the notification again and start another run.

Important

When you save, Quickbase may show a Notification Error saying the account may only send email to verified Quickbase users. If so, submit a technical support case to allow your account to send emails to non-registered Quickbase users.

Status messages

The trigger field (the field in xldbtfld, or in triggerfid) shows where the run is:

If you set logsdbid, each run also adds a record to the XL Docs Batch Processing Logs table, related to the record that started it:

Batch configuration messages

The batch processor always checks the arguments against the saved batch configuration (enhanced security) before it creates anything. If the check fails, the run stops and the message is written to the trigger field in xldbtfld (when xldbdbid, xldbrid, and xldbtfld are set). The bulk setup sets them, so the message appears in the Trigger Field on the XL Docs Batch Processing record. The single-record setup doesn't, so by default the message isn't recorded anywhere; add all three to the XL Docs Batch Processing Arguments formula to see it.

See Use a configuration in batch runs and Batch Config Portal messages and troubleshooting.

If nothing happens

• Check that the trigger field contains Requested after the click, and that the notification is Open, sends to the batch address, and has the contains Requested condition.

• Check that the message body contains only the arguments field.

• The batch processor needs clientid, appid, fn, dbid, tpdbid, tpid, and exactly one of msid or msqry/msqid. If any is missing, no documents are created and no status is written. If you give both msid and msqry, the run stops with Supply either 'msid' or 'msqry', not both.

• If your app isn't authorized for XL Docs (for example, its authorization was removed in the Extensions Portal, or the saved user token is no longer valid), the run stops without changing the trigger field. Check the app's authorization in the Extensions Portal (see Authorization).

• If the trigger field shows Batch Execution Requested_ for a long time, submit a technical support case.