In this chapter…

…we will discuss automating AppendPDF and AppendPDF Pro with scripts. Content that is specific to AppendPDF Pro is followed by the notation: (AppendPDF Pro only).

It is likely that you will wish to incorporate AppendPDF or AppendPDF Pro into scripts that you build to make appending and delivering documents an automatic process.

AppendPDF and AppendPDF Pro, as command-line driven applications, can be run from any programming or scripting language (or other application) that can make a call to a command line.

This is especially true for regular weekly and monthly reports, or web pages that contain variable information, but in a consistent or standardized format. For example: a monthly sales report can be automatically generated by programmatically selecting individual sales reports from a standard set of directories. In addition to appending the periodic reports into a single document, a cover sheet, table of contents, and bookmarks can be generated.

When AppendPDF or AppendPDF Pro is combined with Appligent’s FDFMerge product, an application that merges FDF data files with PDF forms, it becomes practical to generate a complete report from dynamic information that is either entered manually (for example, via web forms) or automatically using database queries. Individual standardized report sections can be automatically filled in and saved into a standard set of directories with standardized file names. These dynamically generated PDF sections can then be appended into a single document.

Be Aware of Your Options

In addition to dynamic control of automatic document generation via parameter files, you can dynamically utilize the AppendPDF or AppendPDF Pro command-line options to produce different output under different conditions. Options to consider when dynamically executing AppendPDF or AppendPDF Pro include:

  • Showing Progress (-p) — An if statement can determine whether this is an interactive run or a background run and can then turn progress on or off as appropriate.
  • Writing to a Log File (-l <logfile>) — This is usually a good idea for batch document processing. Either the same log file can be appended, or a new log started with each run. A sophisticated script could check the log for errors and e-mail the administrator with any problems.
  • Adding Bookmarks (-b) — Whether a script is designed to be interactive or run in the background as a batch process, an argument can be set to turn bookmarks on or off according to user preference.
  • Version Information (-v) — Using this option with the log file option will capture the product version information in the log file.

When dynamically generating a parameter file, you should consider such options as:

  • Page ranges — Using page ranges lets you specify partial documents to be included, and the -1 notation can be used in a range to indicate the last page.
  • Document info — Any information you would like to attach to a document can go into the Document Info area of the output file.

Dynamically Generate Parameter Files

One way to automate AppendPDF or AppendPDF Pro would be to avoid having to type in each of your source files in the parameter file by creating a simple shell script to enumerate the contents of a directory directly into the parameter file.

Dynamic parameter files may be generated from Perl, Java, VBScript, Tcl or any shell script. Developing scripts to generate parameter files is a more efficient approach to PDF document generation when the document contents, file paths, and parameters are variable. Such scripts are also easier to maintain than many separate static parameter files.

For larger batch document runs, you can take advantage of the ability of AppendPDF and AppendPDF Pro to process several parameter files at a time.

The dynamic generation of one or more parameter files enables you to utilize the full power of AppendPDF and AppendPDF Pro. Examples of some of these advanced capabilities, include:

Cover page block — AppendPDF Pro only

The user could select from a list of pre-made cover pages, or select from any desired combination of cover sheet and cover sheet stamps. This would permit periodic “standardized” reports to retain a fresh look with each edition.

TOC block — AppendPDF Pro only

In addition to turning Table of Contents (TOC) information on or off, the user could be given the option of determining the appearance of the TOC by selecting from a list of standardized fonts, font sizes and colors. The application of stamp(s) to the TOC (for example, page numbers) could also be optional. The user could even override the default section titles in the generated TOC.

Extras block — AppendPDF Pro only

Since Extras stamps are only applied to the body of the generated document and not to the Cover Page or TOC, the user can be encouraged to provide additional stamped information for the body, for example, in the page header and footer. Stamped information containing text strings can contain variable items. An appropriate stamp could be programmatically generated or selected from a pre-defined or pre-generated collection of stamp files (for example, one for each department, group, or individual for which the document is targeted).

Dynamically generate stamp files — AppendPDF Pro only

The same considerations that have been given to dynamic parameter file generation can be given to the dynamic generation of stamp files. By combining both techniques, an up-to-date or even fully custom document can be generated. Either the user or the program can provide values for such variables and attributes as:

  • Text to be stamped
  • Stamps for the cover page
  • Stamps for the TOC
  • Headers and Footers
  • Watermarks (DRAFT, Confidential, etc.)
  • Font, Font Size and Color of the Stamped Text
  • Text Mode (solid, outline, invisible)
  • Location or Position of the Stamped Text
  • Pages (and pages within Sections) to receive a particular stamp
  • % variables for dates, times, page numbers and section numbers

Since AppendPDF Pro is sensitive to the exact format of stamp files, it is very important to understand the format requirements and that the program or script generates only well-constructed stamp files (for example, balanced parentheses, % signs, etc.).

Develop Large Documents in Stages

Large documents should be developed in stages, rather than in a single AppendPDF or AppendPDF Pro execution, so the results of each processing stage can be checked before proceeding. Customizations can be applied to each individual stage as well as to the final document as a whole. All of this “multi-stage” processing could be accomplished under the control of a single program or script, for example, a period (daily, weekly, monthly) report or web-content generation program.

AppendPDF and AppendPDF Pro can be integrated into a program or script that generates multiple parameter files, then executes AppendPDF or AppendPDF Pro to compile various “Sections” or “Chapters”. Then after error checking, append the resultant PDF documents into a single complete PDF document. A file listing all parameter files can be used as the input to a script for a single execution of AppendPDF or AppendPDF Pro.

The illustration below shows appending multiple sections in stages with AppendPDF Pro. When running AppendPDF, there will be no Table of Contents (TOC) or cover page generated since AppendPDF does not have those features.

Appending multiple sections with AppendPDF Pro

Error Checking

When dynamically generating parameter files and executing AppendPDF or AppendPDF Pro with various option settings, it is important to perform checks in your scripts to eliminate or minimize possible errors that may otherwise occur. Common errors to search for:

  • source file path strings for internal spaces—especially true of MS Windows file names
  • source file path strings for internal commas

If errors are found, then the script or program can report them and log them and either halt the AppendPDF or AppendPDF Pro run or skip the appending of the erroneous files such as a section or chapter. A script could also insure that file paths are processed properly by surrounding the paths with double quotes.

A complex script or program could perform an operating system level check for the existence of each file path and check to make sure the read-permission is correct before proceeding.

When generating even moderately large or complex documents into “compound documents” that include separate sections, a cover page and a TOC (AppendPDF Pro only), it is prudent to programmatically check the results (return codes, error log contents, etc.) of each step before proceeding to the next, thus eliminating an attempt to append all of the components into an incorrectly created document.