RenderPptx

This configuration sets general rules how pptx rendering is done.

The configuration is located in /renderpptx/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

RenderPptx 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/renderpptx/config.ion

{
	allowMultiplePlaceholderPerName : false,
	allowMultiplePlaceholderPerType : false,
	allowMultipleShapesPerName : false,
	insertNewSlidesAfter : 0, // slide number is 1-based
	keepExistingSlides : false,
	mapPlaceholdersByName : true,
	mapPlaceholdersByType : false,
	mapShapesByName : false,
	preferredView : "normal",
}

Global Defaults

// /renderpptx/config.ion
{
  documentTemplate : "default",
  keepLog : "onerror",
  keepLogForSeconds : 86400,
  keepLogUntil : "shippedOrExpired",
  keepOutput : "onsuccess",
  keepOutputUntil : "shippedOrExpired",
  keepOutputForSeconds : 86400, // 1 day
  maxExecutionMillis : 3600000, // 1 h
  redeliverOnError : []
}

documentTemplate

Optional name of the document template for the pptx process.

• Data Type: String
• Default: default

Requirements

• The name documentTemplate must correspond to a pptx template file in the powerpoint folder of the pptx project (i.e. /powerpoint/default.pptx in the /renderpptx folder given the example above).
• the default document template is named "default" and therefore points to a file default.pptx

Places to define documentTemplate in order of precedence:

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

maxExecutionMillis

Optional maximum runtime for the pptx process.

• Data Type: int
• Default: 3600000 (1 h)

If maxExecutionMillis is exceeded then:

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

Output Handling Configuration

keepOutput

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

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

keepOutputForSeconds

Optional expiry duration for pptx artifacts.

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

keepOutputUntil

Optional rule for deletion of the log.

Data Type: Enumeration

• shipped: delete pptx after the output was successfully "shipped" (see below) to the end user
• expired: delete pptx if expiry is exceeded
• shippedOrExpired: delete pptx if job artifact state matches any of "shipped" or "expired"
• forever: do not delete pptx automatically on a job event (PPTXs 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.
  • pptx artifact was downloaded successfully via REST API endpoint GET /{project}/storage/{ticket}.
• A pptx 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. pptx.log.

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

pptxLog

Optional flag to enable logging of pptx.

This maps to the pptx flag --log.

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

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

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 pptx process ends
  • onerror : log files are stored only if pptx process ended with an error
  • onsuccess: log files are stored only if pptx 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.
  • pptx 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 pptx occurs during rendering.

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

Using more than one Redelivery object can be useful if different pptx exitCodes should lead to different kind of redeliveries: If a pptx 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.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
  }  
]}