Skip to main content

RenderPdf

This configuration sets general rules how comet_pdf rendering is done.

The configuration is located in /renderpdf/config.ion.

The configuration file itself is optional.

All properties in the configuration file are also optional.

Project config files inherit properties from tenant config files which inherit from the global defaults as given below.

Typical Project Configuration Example​

RenderPdf config differ a lot in practise. So, the following gives on a hint for how they look like. It is not meant as boilerplate code.

// /tenants/mytenant/projects/myproject/renderpdf/config.ion
{
  buildScript : "build.py",
  cometPdfVersion : "R34005",
  keepLogForSeconds : 1800, // 30 min
  keepLogUntil : "expired",
  keepOutputForSeconds : 1800, // 30 min
  maxExecutionMillis : 60000, // 1 min 
  redeliverOnError : [ {
    maxRedeliveries : 1,
    redeliverIntervalMillis : 60000 // 1 min
  } ]
}

Global Defaults​

// /renderpdf/config.ion
{
  additionalCometPdfArguments: null,
  buildArguments : null,
  buildScript : null,
  cometLog : "enableLogOnError",
  cometPdfVersion : "R32735",
  documentTemplate : "default",
  keepLog : "onerror",
  keepLogForSeconds : 86400, // 1 day
  keepLogUntil : "shippedOrExpired",
  keepOutput : "onsuccess", 
  keepOutputUntil : "shippedOrExpired", 
  keepOutputForSeconds : 86400, // 1 day
  maxExecutionMillis : 60000, // 1 min
  pdfLibLog : "enableLogOnError",
  redeliverOnError : [] 
}

Comet Command Configuration​

additionalCometPdfArguments​

Optional comet_pdf command line arguments.

This is an expert feature. Please read the comet_pdf documentation for "command line arguments".

WARNING: Supported command line arguments depend on the cometPdfVersion you use. Unsupported arguments or arguments with unsupported values will be silently ignored. Please check the comet.log file for the arguments that are actually applied.

  • Data Type: Object
  • Default: null

Example:

{
  // ...
  "additionalCometPdfArguments" : {
    "CHECK_WEBIMAGES" : "1"
  }
}

buildArguments​

Optional global arguments for the comet_pdf process.

This is an expert feature. Please read the comet_pdf documentation for "global arguments", their declaration and usage.

  • Data Type: Object
  • Default: null

Hint: Build arguments will be set with the related command line option -g. Only arguments of type "char" are supported here.

Example:

{
  // ...
  "buildArguments" : {
    "gConfigId" : "foo bar"
  }
}

buildScript​

Optional build script name for the comet_pdf process.

What is a build script?

  • See comet_pdf documentation.

  • Data Type: String (file name)

  • Default: null

Requirements

  • Build script name should end with extension '.py' or '.crpt' for Python script or CScript.
  • The build script name must correspond to a file in the scripts folder of the comet project (i.e. /scripts/foobar.py in the /renderpdf/comet_xml.zip).
note

If buildScript is not set renderpdf will search for a build script in /scripts/build.py or /scripts/build.crpt in this order. If none of these exist then the build command "place" will be used. See details for "place" in the comet_pdf documentation.

cometPdfVersion​

Optional version of the comet_pdf application to be used for rendering.

  • Data Type: String
  • Default: R32735 (at the time of writing)
caution

The default may change without further notice, since comet_pdf evolves continuously.

tip

It is recommended to use an explicit version name here and not rely on the default.

documentTemplate​

Optional name of the document template for the comet_pdf process.

  • Data Type: String
  • Default: default

Requirements

  • The name documentTemplate must correspond to a w2ml file in the master-documents folder of the comet project (i.e. /master-documents/foobar.w2ml in the /renderpdf/comet_xml.zip given the example above).

Places to define documentTemplate in order of precedence:

  • query parameter of the REST API e.g. POST /renderpdf?documentTemplate=foobar)
  • config property in /restapi/config.ion
  • config property in /renderpdf/config.ion
  • config property in global default

maxExecutionMillis​

Optional maximum runtime for the comet_pdf process.

  • Data Type: int
  • Default: 60000 (1 min)

If maxExecutionMillis is exceeded then:

  • The running comet_pdf process is destroyed.
  • ExitCode 504 will be registered.
  • A "fatal" message will be written to the comet.log like Process 5478 ended by force. Timeout reached (60000 msec).

Output Handling Configuration​

keepOutput​

Optional rule to set whether the PDF files should be stored in the backend.

  • Data Type: Enumeration
    • never : PDFs are deleted immediately after the comet_pdf process ends
    • onerror : PDFs are stored only if comet_pdf process ended with an error
    • onsuccess: PDFs are stored only if comet_pdf process ended with a success
    • always: PDFs are stored in any case
  • Default: onsuccess

keepOutputForSeconds​

Optional expiry duration for PDF artifacts.

  • Data Type: int
  • Default: 86400 (1 day)

keepOutputUntil​

Optional rule for deletion of the log.

Data Type: Enumeration

  • shipped: delete PDF after the output was successfully "shipped" (see below) to the end user
  • expired: delete PDF if expiry is exceeded
  • shippedOrExpired: delete PDF if job artifact state matches any of "shipped" or "expired"
  • forever: do not delete PDF automatically on a job event (PDFs might be deleted later due to other cleanup processes)
  • Default: shippedOrExpired
note
  • A job artifact is considered as shipped if one of the following is true:
    • Upload worker ends successfully with HTTP 2xx.
    • PDF artifact was downloaded successfully via REST API endpoint GET /{project}/storage/{ticket}.
  • A PDF is considered as expired if keepLogForSeconds is exceeded.
  • Deletion may not happen immediately because files often are only "marked" for deletion.

Log Handling Configuration​

The following properties mainly control the handling of log files, esp. comet.log.

The storage properties (keepLog, keepLogUntil, keepLogForSeconds) apply to all files created during the comet_pdf call except for the PDF artifact itself. This includes comet.log, pdflib.log, data.xml, items.xml, etc.

cometLog​

Optional flag to enable logging of comet_pdf.

This maps to the comet_pdf flag --log.

Log file will be stored as comet.log in the output folder for the job.

  • Data Type: Enumeration
    • on: always on
    • off: always off
    • enableLogOnError: on after first comet_pdf error for a job happens
  • Default: enableLogOnError
tip

This is an expert feature. Never activate pdflib logging in "production" mode. Only activate it if you expect very low level issues and if you are familiar with the logging format of pdflib.

pdfLibLog​

Optional flag to enable logging of the pdflib.

This maps to the comet_pdf flag -u.

Log file will be stored as pdflib.log in the output folder for the job.

  • Data Type: Enumeration
    • on: always on
    • off: always off
    • enableLogOnError: on after first comet_pdf error for a job happens
  • Default: enableLogOnError
tip

This is an expert feature. Never activate pdflib logging in "production" mode. Only activate it if you expect very low level issues and if you are familiar with the logging format of pdflib.

keepLog​

Optional rule to set whether the log files should be stored in the backend.

  • Data Type: Enumeration
    • never : log files are deleted immediately after the comet_pdf process ends
    • onerror : log files are stored only if comet_pdf process ended with an error
    • onsuccess: log files are stored only if comet_pdf process ended with a success
    • always: log files are stored in any case
  • Default: onerror

keepLogForSeconds​

Optional expiry duration for log files.

  • Data Type: int
  • Default: 0 (seconds)

keepLogUntil​

Optional rule for deletion of the log.

Data Type: Enumeration

  • shipped: delete log files after the output was successfully "shipped" (see below) to the end user
  • expired: delete log if expiry is exceeded
  • shippedOrExpired: delete log if job artifact state matches any of "shipped" or "expired"
  • forever: do not delete the log automatically on a job event (logs might be deleted later due to other cleanup processes)
  • Default: enableLogOnError
note
  • A job artifact is considered as shipped if one of the following is true:
    • Upload worker ends successfully with HTTP 2xx.
    • PDF artifact was downloaded successfully via REST API endpoint GET /{project}/storage/{ticket}.
  • A log is considered as expired if keepLogForSeconds is exceeded.
  • Deletion may not happen immediately because files often are only "marked" for deletion.

Error Handling Configuration​

redeliverOnError​

This configuration is applied if an error in comet_pdf occurs during rendering.

  • Data Type: Array of Redelivery objects
  • Default: empty array

Using more than one Redelivery object can be useful if different comet_pdf exitCodes should lead to different kind of redeliveries: If a comet_pdf error occurs the exitCode is matched against the codePattern of the Redelivery objects in their order. The first matching Redelivery rule will be applied.

redeliverOnError.codePattern​

Optional regular expression to match the numerical exitCode of the comet_pdf process.

Error codes are listed in https://kb.priint.com/comet/InDesign/Plugins/comet_pdf.html#Exit_values. Additionally, you may receive general error 127 meaning that the start comet_pdf already failed.

  • Data Type: Regular Expression String
  • Default: .* (match all)

redeliverOnError.maxAgeMillis​

Optional maximum age of a redelivery job.

A redelivery rendering that fails after this interval will automatically be regarded as a terminal error. Thus stopping the redelivery cascade even if maxRedeliveries is not reached. The job will then be dropped and the error webhook will be executed (if configured).

This property is useful if you set maxRedeliveries > 1.

  • Data Type: int
  • Default: 0 (no age restriction)

redeliverOnError.maxRedeliveries​

Optional number of redelivery attempts until dropping the job and executing the error webhook (if configured).

  • Data Type: int
  • Default: 0 (no redeliveries)
tip

In most cases 1 is the best value: maxRedeliveries=1 means that rendering will be regarded as failed after 2 failed attempts. Waiting a longer time rarely solves the problem then. Do not set this to more than 2.

redeliverOnError.redeliverIntervalMillis​

Optional number of msec to postpone the redelivery of the job.

This is a minimum interval. The job will be rescheduled after the given interval. The real start time of the rescheduled job depends on the load of the rendering queue.

  • Data Type: int
  • Default: 0 (immediately scheduled for redelivery)
tip

Do not set this property to 0. Errors may happen due to short living causes (e.g. a temporarily slow MAM system). Give the redelivery a chance to succeed by postponing it for some seconds or minutes.

Redelivery Example​

// try up to 2 redeliveries if exit code is any of 137 or 139 and wait for 180s between the attempts
// otherwise try up to 1 redelivery wait for 60s between the attempts
{ redeliverOnError : [ 
    {
      maxRedeliveries : 2,
      redeliverIntervalMillis : 180000,
      codePattern : "137|139"
    }, {
      maxRedeliveries : 1,
      redeliverIntervalMillis : 60000
  }  
]}