Step by step - Learn how to use callas productscallas pdfToolboxServerSidecar files and their use when processing files with a Server-Job

Sidecar files and their use when processing files with a Server-Job

With sidecar files, it is possible to add a file to the input hotfolder (that has the input PDF) which contains additional information in the form of Variables. This information can be used and modified during the hotfolder processing. The new (updated) values can be used to influence processing in later hotfolder steps.

Using Sidecar files

  • When sidecar files shall be used, no new entry in the configuration of a Job is necessary - if a *.sidecar-file exists beside a PDF, their content is just used for processing.
  • Values of the "variables" in the .sidecar-file are used as Variables for every Job.
  • To  use new values (e.g. calculated or set in previous hotfolder jobs) for Variables, they have to become grabbed up from the results area and it must be handled in the JavaScript Variable in that way, that their value overwrite the existing Variables during runtime.
  • A .sidecar-file can not contain additional CLI commands or options.
  • A .sidecar-file should exist at least simultaneously to the input file inside the input folder. It is recommended to copy the .sidecar-file before the input file to ensure the Server is aware of the sidecar file when scanning the input folder.

Syntax of Sidecar files

As already mentioned, optionally a .sidecar-file can be copied into the In folder beside the input file. The content of the .sidecar-file will be taken into account for processing. But the general parameters from the Job settings will control the way a file is handled.

The ".sidecar" file has to be formatted in JSON, containing all additional information for processing a file.

The .sidecar-file must have the exact, case-sensitive same name as the original file, e.g.:

  • Inputfile.pdf
  • Inputfile.pdf.sidecar
{
   "type":"sidecar",
   "variables":
   [ 
      { 
         "key":"placetext",
         "value":"Some text from the initial sidecar file"
      },
      { 
         "key":"activate_fixup",
         "1"
      }
   ]
}
Click to copy

Each Job Ticket has to start with the "type", which must be "sidecar".

Within the "variables" section new values for Variables can be defined, which will then be used for the specific file.

Updated content after a Job

The normal "variables" part will not be updated, if a Variable has changed during processing.
However, all changed Variable as well as details to every performed processing step is added to the .sidecar-file as shown in the sample below:

{
	"results" : 
	[
		
		{
			"command" : "< complete CLI command used >",
			"folder_in" : "/Hotfolder/Job_2/In",
			"jobname" : "Sidecar Job",
			"returncode" : 5,
			"variables" : 
			{
				"placetext" : "Some text from the initial sidecar file",
				"placetext_new" : "Some text from the initial sidecar file and some additional text",
				"script" : "Some text from the initial sidecar file and some additional text"
			}
		}
	],
	"type" : "sidecar",
	"variables" : 
	[
		
		{
			"key" : "placetext",
			"value" : "Some text from the initial sidecar file"
		},
      { 
         "key":"activate_fixup",
         "1"
      }
	]
}
Click to copy

In this sample, a new Variable "placetext_new" is created by a JavaScript-Variable in the Profile. It uses the supplied, new "placetext"-Variable and just adds some additional text.

Create Sidecar files from a Server-Job

It is possible to create a .sidecar-file if not existing by activating the respective option within the four settings for each severity. Creating such a .sidecar-file enables a pick-up of results by following steps.

Download of the used sample Profile

Everything from 'How to' to 'Do's and Dont's' of Sidecar files in this video: