“Where is” series, JavaScript in batch processing

Learn how to split documents, add stamps, fill in document metadata, and more.

By Thom Parker – July 7, 2006

 

Scope: Acrobat Professional 6.0 and greater
Skill Level: Intermediate
Prerequisites: Familiarity with Acrobat Professional & Acrobat JavaScript

Batch Processing is a way for Acrobat to operate on large numbers of documents (for example, to split documents, add stamps, fill in document metadata, and so on). To do batch processing the user first builds a list of commands (or actions) called a Batch Sequence. Acrobat includes a built-in list of common commands from which to choose. Third party plug-ins can also add commands to this list. When the sequence is run, Acrobat applies the list of commands to each file it processes.

Batch processing works great until you want to do something that either needs more flexibility or isn’t in the list at all. What do you do then? The answer is provided by one of the common commands built into Acrobat, the “Execute JavaScript” command. Scripting greatly increases the number of operations that Batch Processing can apply to a document. It includes, of course, everything that can be done with Acrobat JavaScript and adds intelligence to how operations are applied to a PDF.

The Execute JavaScript Command

The files on which a Batch Process operates are opened one at a time. The complete list of commands in the Batch Sequence is applied to the opened file. It is then saved and closed before the next file is opened. From inside the Batch Script, the currently open document is referenced with either the this or event.target properties, both of which are equivalent. Batch Processing is aborted if the event return value, event.rc, is set to false. Also, Batch Processing is one of the few privileged, or completely unrestricted, execution contexts. Any property or method in Acrobat JavaScript can be used in a Batch Sequence Script.

A typical task for a Batch Script is to add or modify custom metadata. There is a command for modifying the standard metadata parameters such as the title, author, or keywords, but not one for custom metadata, so we have to do this task in JavaScript. The following Batch Script adds a version number, copyright notice, and the name of the user to custom metadata entries. It also aborts the Batch Processing if a document modification date is earlier than March 2^nd, 2001.

this.info.copyright = "Copyright \u00A9 " + this.modDate.getFullYear(); + " by " + identity.corporation; 
this.info.version = "1.34.06"; 
this.info.modifiedBy = identity.name; 
event.rc = (this.modDate > (new Date("3/2/2001")) );

Batch Processing and this script now make easy work of updating hundreds or thousands of documents. The script not only allows us to access document properties that aren’t available in the built-in Batch Sequence Commands, but it allows us to customize the operations performed on each document.

Creating a Batch Sequence

To edit or create a Batch Sequence:

1. Use the menu item:

Advanced>Batch Processing …

This menu item displays the Batch Processing Dialog (Figure 1).

2. Press the New Sequence button.

3. Enter a Name for the new Batch Sequence and press OK to display the Batch Sequence editing dialog.

4. Press the Select Commands… button to display the Sequence editing dialog.

5. Scroll down the command list to find the Execute JavaScript command. Select it and press the Add >> button to append it to the sequence.

6. To edit the JavaScript, double click the Execute JavaScript command in the Batch Sequence list (the one on the right side of the dialog).

7. Enter the Batch Processing JavaScript and exit the editor.

8. You now have a Batch Sequence that uses JavaScript to operate on the documents.

Batch scripts are used for tasks as diverse as building document summaries and indexes to complex operations like custom splitting and merging. Literally any Acrobat JavaScript functions or properties can be run from a Batch Script, but there are some good rules of thumb to follow:

1. Don’t use functions that display user interface items like menus, dialogs, or alert boxes. Using these items defeats the purpose of batch processing since the user will have to monitor the process and possibly have to click buttons and enter text for each file processed.

2. Don’t perform unreliable operations. There are functions in Acrobat that rely on not so reliable services like internet connections and external files. Since the batch process is operating automatically in its own world, any code that hangs will slow or stop the process without necessarily giving the user any indication there is a problem.

3. Use exception handling, error messages, and progress logging. Because of the problems outlined above, Batch Scripts should catch and report any exceptions or other problems (usually to the JavaScript Console). It’s also helpful, but not as important, to indicate success on each document. Without these measures there is no way to tell if the script operated properly without examining each document individually.

4. Don’t perform lengthy or inefficient operations. This is of particular importance when processing hundreds or thousands of documents. It is not unusual for batch processing to run for days, so the performance of each line of code is important.

5. Test and verify all code in the JavaScript Console before placing it in a batch process.

6. In general, Batch Scripts should be able to be run unattended.