Taking variables to the next level

Variables have originally been introduced in 2009 in pdfToolbox 4, and have proven to be a very flexible and powerful instrument to develop efficient workflows. Based on extensive feedback from our customers and OEM partners, we have extended the way variables work in pdfToolbox in several ways:

  • More aspects of Profiles, Checks and Fixups can be handled through variables; for example, it is now possible to turn Checks on or off, change their severity, or to use variables for Check boxes and pop-up menus
  • Variables are now self contained data objects; this is especially useful where the same variable is used in more than one place; in the past, a pdfToolbox user had to ensure that the same variable used in more than one place was using the exact same configuration string.
  • Variables can now also be used as a step in a Process Plan, such that the execution of the following steps can depend on the evaluation of the variable in this step.
  • Beyond being a kind of an advanced placeholder with predefined default values, variables can now also be defined in the form of a JavaScript; this implies the possibility to derive the value for a variable from other variables, or from the metadata or filename of the current PDF, or from result data from a previous preflight Check.
  • Where JavaScript is used, internal variables can be defined and used, without ever confronting a pdfToolbox Desktop user with it.
  • In the context of a pdfToolbox Profile, it is possible to include a JavaScript that could for example do preparatory calculations, or determine the value of other variables depending on a document's metadata, filename, or other information.

The concept of "variables"

Variables as used in pdfToolbox are small information objects that come in two flavors:

  • simple value variables
  • script based variables

Each data object for a variable has four properties:

  • a key (for use when configuring values in Process Plans, Profiles, Checks or Fixups, and for working with variables in JavaScript)
  • a label (for use in the user interface, for example in the "Ask at runtime" dialog)
  • a value (either, in the case of a simple variable, a default value to be used unless a different value is provided at runtime, or a JavaScript that once evaluated will return the applicable value)
  • an internal unique ID (not displayed in the user interface, but can be retrieved using JavaScript)

A variable can be used in almost any context where something can be configured in any of the following:

  • Process Plans
  • Steps in Process Plans
  • Profiles
  • Checks
  • Fixups
  • Checks used as filters in Fixups

The places where variables can be used are for example:

  • name and description fields
  • fields of type Check box, popup, or input fields for text or numbers
  • severity for Checks and Fixups inside a Profile
  • ON/OFF switch for Checks and Fixups inside a Profile

Variables make it possible to determine some information that is useful when executing a Process Plan, Profile, Check or Fixup at the time of execution, instead of having to predefine such information beforehand. A simple example would be a Check that analyses the minimally required  resolution of images. Sometimes 300 ppi are needed (for high quality printing, in other cases 72 ppi or 96 ppi could be sufficient (when sharing a PDF via email). While it is possible to configure three separate Checks for 300 ppi, 96 ppi and 72 ppi, it is much more elegant to only define a single Check, where a place holder is used which is then filled when executing the Check. Not only is just one Check needed instead of three, it is also absolutely easy to use the same Check for altogether different required minimal resolutions, like 144 ppi or 450 ppi or any other value.

Thus, the major benefit of variables is the option to postpone the decision, which values to use for processing PDFs, to the moment when processing is started. This includes the possibility to choose different values each time. Furthermore, the introduction of JavaScript makes it possible to derive further information based on information provided at runtime or based on information through metadata, including the option to use relative complex calculations.

Variables in the desktop, server, and command line SDK versions of pdfToolbox

In the desktop version of pdfToolbox (whether Acrobat plug-in or standalone), when running a Process Plan, Profile, Check or Fixup that contains one ore more variables for which input is needed, the "Ask at runtime" dialog will open and will request that user enters values as desired (or leaves the pre-populated default values as they are). For the server and command line versions, the values have to be provided as command line parameters or by means of a configuration file.

Important to note:

  • Values entered by the user have to be suitable for the type of field for which they are to be used; for example, it is now impossible to provide arbitrary text when the expected value is a number.
  • Additional information is provided to the user in the "Ask at runtime' dialog in case there is a problem with the value(s) entered.
  • Using a special option in the "Ask at runtime" dialog, it is possible to analyze the way variables are collected or calculated; this not meant to be used by the typical user, but rather by the person in charge of developing advanced uses of variables – which could become quite complex in Profiles that use variables in many places in Checks and Fixups.

Important to note here is that: There is no error reporting for Checks if Variable value has wrong data type (example: 'null' as value where a number is expected)

How powerful is the JavaScript engine in pdfToolbox?

The JavaScript engine in pdfToolbox is based on Google's V8 JavaScript engine (see https://developers.google.com/v8/ for more information). Those who work with JavaScript in browsers will know, that sky is the limit there. One could carry very extreme tasks using JavaScript inside a browser, including reaching out to all kinds of services and data sources over the internet.

The way JavaScript functionality is provided inside pdfToolbox takes a slightly different approach:

  • pdfToolbox (through the underlying V8 engine) supports the complete set of JavaScript features as defined in ECMAScript is specified in ECMA-262, 5th edition (see http://www.ecma-international.org/publications/standards/Ecma-262-arch.htm)
  • several pdfToolbox specific internal data objects, in order to allow for access to document metadata, filename, and so on; and to store data in a place shared across Process Plans, Profiles, Checks and Fixups through one execution context.
  • The pdfToolbox JavaScript engine comes with a powerful runtime evaluation architecture, that ensures that variables relying on each other do actually work consistently without the user having to meticulously take care of such dependencies.
  • pdfToolbox does not offer any access to outside data (except where provided through pdfToolbox specific internal data objects), whether to the local file system, or to web services or data accessible "over the web"
  • pdfToolbox also does not offer the possibility to reference JavaScript files, as is often used to provide JavaScript libraries; where library-like functionality is needed, suitable JavaScript code must be included in the JavaScript snippet associated with a variable, or with the Profile JavaScript.