Simple variables

Variables can be defined in several places in pdfToolbox, e. g. in the editor of Profiles, Checks, Fixups or Process Plans. Variables may be assigned to virtually every control including the severity for a Check:

  • Text input fields
  • Checkboxes
  • Pop Up fields
  • Severities
  • On/Off switch in order to enable/disable for example a Checks or Fixups in a Profile or Process Plan

Assign a variable

When you click on a variable icon (orange triangle), you will see a list of all variables that are present in the system. Variables that are used in the current context (e.g. the current Profile) appear at the top. You may pick any of the existing variables (1), create a new one (2) or edit one that is already assigned (3).

Two types of variables

As you may have seen, there are two different types of variables:

A simple variable can be inserted into a parameter of e. g. a Check to make it dynamic. When the Check is run in pdfToolbox Desktop, the software asks the user which value to insert for the variable.

Script variables are defined in the form of a JavaScript; this allows deriving the value for a variable from other variables, from the metadata of the current PDF file, or from the results of a previous preflight Check. If you want to learn more about script variables then you can find everything in the next article: Variables using JavaScript: Overview

Variable Editor: creating a new variable

To define a variable pdfToolbox needs at least three pieces of information: key, label and default value.

  1. Key:  for internal use and use on the command line to address the variable (therefore the key should be unique).
  2. Label: for use in the user interface, for example in the "Ask at runtime" dialog.
  3. Type: Simple value (simple variable) or Script (JavaScript-based variable). Tip: on the right side the value type is always specified, which must be used for the default value. The following types are available (Float, Sting, Boolean, Pop-up, Integer).
  4. Default value: to be used unless a different value is provided at runtime.
  5. Allow Browser button in feasible: determines whether a browse button is displayed in the Ask-at-runtime dialog when executed in pdfToolbox Desktop, allowing the user to select a file from the system (e.g. to load an ICC profile).
  6. Limit input values to specific values: you may define restrictions (this is explained in a later step in this chapter).
  7. Show evaluation results: if enabled, a console will be available for debugging.

Default values for Checkboxes and PopUps

If the parameter for which a variable is to be created is a Checkbox or a PopUp, only predefined values are valid for the default value:

A checkbox has the value type Boolean, which means that only two default values are valid: 0 (checkbox is disabled) or 1 (checkbox is enabled). Other values are not valid.

The value type PopUp has always an info button in the variable editor, which contains all valid values. The example below shows the default values for the severities of a Check. You can choose between 4 severities: Inactive, Info, Warning, Error. Depending on which severity is selected in the info dialog, the appropriate default value is added to the variable. In our example the severity should be "Error" as default, which has the default value 3.

Limit input values to specific values

Constraints can be defined by using the "Limit input values to specific values" checkbox in the variable editor. There are two ways to limit the input values: the value provided for the variable can be limited to a range, or it can be limited to a list of predefined values.

Constraints - List

The entries that are defined under "Values" are used as a list, and will be shown as PopUp in the Ask-at-runtime dialog of pdfToolbox Desktop. That means that only the predefined values can be selected by profile execution.

The values must be entered one below the other and the default value must be included in the list.

In this example, the values defined in the list are available for selection during profile execution in the "Ask at runtime" dialog, i.e. 8, 10 and 12.

Constraints - Range

When you are using the Range option, two values will define a range, so it only accepts a number between these two values. In this example, all values between 300 and 400 can be specified in the Ask-at-runtime dialog. Values outside this range are not allowed.


Special feature: multiple ranges can be specified as well as a single value. As soon as two values are added, they form another range. If a single value is added, it is permitted as a single value in addition to the range. In the example below, 5 values100 have been specified: the first two (100, 200) form the first range, the third and fourth values (300, 400) form the second range, and the last value (500) is considered a single value.

Constraints for PopUp fields

You may again use the info button in order to pick possible values for the PopUp. In this example this is done for a severity, but it works in the same way for other Pop up fields.

Variables in Processplans

It is possible to define a variable as a step in a Process Plan. This will work similar to a variable on Profile level and is only useful and effective for script variables.

Managing and deleting a variable

Deleting a variable is currently only possible in the Library Manager (Library drop down> Manage Libraries) and only if the variable is not used. Via the info button you can see in which Profiles the variable is used.

The "Ask-at-runtime" dialog in pdfToolbox Desktop

In pdfToolbox Desktop a dialog shows up, when a Profile/Check/Fixup/Process Plan is executed that has one or more variables – the so called "Ask-at-runtime" dialog. Further information about the Ask-at-runtime dialog can be found here: Ask-at-runtime Dialog: Introduction.