Skip to main content

RenderPdf

This configuration sets general rules for 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 configs differ a lot in practice. So, the following gives a hint for what 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 the 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 a Python script or a 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.

Watermark Handling​

watermarks[]​

Optional array of one or more watermark rules. Each rule has three optional subproperties: file, position, pages. It defines a watermark file (a PDF) to be placed on some or all pages to a foreground or background position.

file​

The file property defines the PDF file to be used as a watermark. The location must be within the comet_xml project. E.g. images/watermark1.pdf. If the file property is not set, it defaults to the built-in priint-cloud watermark.

pages​

The pages property defines the pages where the watermark should be applied. It can have any of the following values. If the property is not set it defaults to default.

  • first: only on the first page
  • last: only on the last page
  • odd: only on odd numbered pages (1, 3, 5, ...)
  • even: only on even numbered pages (2, 4, 6, ...)
  • all: for each page in the PDF the watermark image is taken from the page with the same number in the watermark PDF. If the PDF has more pages than then watermark file, then the watermark file is read from page 1 to the end again.
  • default: same image on all pages

If multiple watermark rules are configured, the rules take precedence in the above order. So if you define a first rule together with an odd rule the resulting PDF will have a watermarks as follows: #1 (first), #2 (no watermark), #3 (odd), #4 (no watermark), #5 (odd), ...

position​

The position property defines where the watermark is placed: before or behind the normal content. The position property takes any of two values foreground or background. The default is foreground.

Multiple rules for foreground or for background build completely different sets and are handled separately.

Error Handling Configuration​

See Redelivery On Error.