JavaScript in pdfToolbox: running potentially sensitive GET and POST calls

In versions of pdfToolbox before version 17, pdfToolbox only exposed the app.http.get method to get information through a web call. And nothing in the way of authentication was supported either. This was done mostly for security reasons.

pdfToolbox 17 and up support "blessed URLs" which all going further with GET and also allow other methods (such as POST).

Blessing URLs

To use this functionality, the URL first needs to be blessed. To alleviate security concerns around shared profiles or process plans, this involves creating a "Blessed hosts" file and adding the URL to it.

The blessed hosts file

The file where URL are blessed has to be created with a specific name and in a specific location:
<callas pdfToolbox preferences folder>/Variables/blessed_hosts.json

The file itself needs to be a valid JSON file with the following content:

{
  "hosts":
  [
    {
      "host": "www.callassoftware.com",
    }
  ]
}
Click to copy

Caution: if you create or edit this file, relaunch pdfToolbox Desktop before testing your JavaScript!

The blessed hosts file is never a part of a profile or process plan. It needs to be installed separately by someone having access to the system.

Crafting an enhanced GET or POST call

Once the URL is blessed, you can extend the app.http.get and app.http.post calls in your JavaScript variables with the following properties:

app.http.get(url, {

	timeout: 100,

	protocol: "http",

	port: 80,

	auth: "usr:pwd",

	headers: { "Accept": "application/json"},

	returnType: "object"

});
Click to copy

To keep sensitive data safe, you can use variables. This would for example allow the "auth" part to be injected into pdfToolbox from outside after retrieving it from secure storage (and not having to keep it in the profile or process plan.

The "returnType" property allows "string" and "object" values and determines whether the call returns the answer as a JavaScript string or a JavaScript object.