Arbitrary JavaScript controlled Fixups

Why this new type of Fixup?

Sometimes you need to do calculations or you want to use lots of variables while configuring one or more Fixups in pdfToolbox. The "Arbitrary JavaScript controlled Fixups" provides a powerful alternative to using regular Fixups in this case.

The Fixup works by providing you with two JavaScript code areas where you can build a configuration for one or more regular Fixups. pdfToolbox then builds the Fixups from the JavaScript objects you provide, and executes them as part of a Profile or Process plan. You shouldn't see this as an easy replacement of standard Fixups, but as an alternative when using regular Fixups would provide very difficult; a good example would be doing color replacement without knowing ahead of time how many colors you want to replace.

Setting up the Fixup

The Fixup contains two JavaScript areas in order to setup it up:

  1. The main JavaScript area. Here, you should create a configuration object and pass it back to pdfToolbox.
  2. The resource area. Here you must list any resources your JavaScript created Fixup requires so they can be properly managed by pdfToolbox

Some property names have been changed in pdfToolbox 13. The old values are still accepted during execution, but if inserted by one of the menu items (“Insert configured fixup…” ec.pp.) the new property names are used. If both properties are present the new property name takes precedence.

pdfToolbox 12 pdfToolbox 13

In pdfToolbox 13, additional Fixup settings have been added to the JSON serialisation:

  "scope" : {
     "current_file" : true,
     "embedded_files" : false

The main JavaScript area

pdfToolbox expects you to return a JavaScript object containing one or more Fixups. The standard form could look something like this:

// The object containing all of the Fixup definitions
const configuration = {
	// A fixup
	flip_pages: {
		config: {
			// fixup specific setup
		displayName: "The name to be used in the report",
		displayComment: "The comment sometimes also shown in reports"

	// Optionally a second, third... fixup

// This line makes sure it is passed back to pdfToolbox. Do not use "return" here.

Some remarks about the code above:

  • "flip_pages" is the identifier for the Fixup we want to use.
  • "config" is where you add the properties for the specific Fixup you are setting up. As each Fixup is different, this section typically will be different for each Fixup.
  • "displayName" and "displayComment" are optional, but allow you to build the name and comment used in preflight reports when this Fixup is run.

So how do you find out what to put in the config area? Click on the blue "i" button (shown as (3) in the screenshot above) and you have three possibilities:

  1. Open list of all base Fixups
    This opens documentation on the setup required for all Fixups.
  2. Insert base Fixup
    This shows you a list of possible Fixups and lets you choose one. pdfToolbox then adds an empty configuration for this particular Fixup to your JavaScript editor so you can further customize it.
  3. Insert configured Fixup
    This is perhaps the easiest and most powerful way to get going. In order to use this, make sure you configure a regular Fixup similar to what you want to recreate with JavaScript and save it (in the same library you're working in with your JavaScript Fixup). Now use this option and your pre-configured Fixup will show up in the list. Select it and the configuration for that specific Fixup, with all properties as you defined them, is inserted into your JavaScript editor.

Things to look out for

While configuring this Fixup is relatively straightforward, there are still some things to be cautious about...

  • pdfToolbox expects JavaScript code, not a JSON object. You'll have to write some JavaScript statements that produce a "result". This result should then contain the setup for the Fixup. You can accomplish this in different ways, but pdfToolbox has no preference - your code simply has to produce a result.
  • You can create multiple Fixups in this JavaScript structure. You can't however have the same type of Fixup twice. If I inserted a "flip_pages" Fixup, I can't add another of those to my JavaScript structure. While there are way to cheat pdfToolbox by inserting something like this into your JavaScript, it's not going to work when you execute the Fixup.
  • Some Fixups internally allow multiple configurations to be setup (using the little "+" and "-" buttons in the user interface when setting up the Fixup). Such Fixups can be configured as well, and in this case the "config" property in your JavaScript structure will be an array. If you're unclear how to do this, create an example Fixup and then use "Insert configured Fixup" to have pdfToolbox show you the way.

Referencing resources

Fixups may use resources, such as ICC profiles or - most importantly - Checks that are used as filters. In order to use such resources they have to be listed in the second input field of the Fixup.


If you are using the method 3. "Insert configured Fixup" described above all configured resources are automatically added. However, even then you may want to add more resources. That is when you want to change what resources are used during runtime. You may for instance want to change the destination ICC profile of a color conversion during runtime via JavaScript. You could then put all ICC profiles that may be used into the "icc_profiles" section of the list and can then reference any of them in the JavaScript.

Or you want to adjust the filter Check that is used.

In order to add any such item to the list you would again use the blue info button.


A simple example to mirror pages horizontally is included here and can be imported into your library. However, with the "Insert configured Fixup" option it's easy to create your own examples. All that's left afterwards is to adjust them to your taste!