REST API

This configuration sets general rules how input data to REST API endpoint like POST /renderpdf are transformed into jobs for the rendering backend.

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

// /tenants/mytenant/projects/myproject/restapi/config.ion
{
    // uploads should always use this endpoint
    uploadUrl : "https://foo.bar/assets/uploader",
    // on upload error we want sent an information to our message channel 
    errorUrl : "https://foo.bar/message-channel/priint-error_a6d62a46a3dfa1a25b919d7d893d8449", 
}

In most projects only the necessary webhook URIs will be configured to set the target endpoints where PDF binaries or notifications will be sent to.

Global Defaults

// /restapi/config.ion
{
    callbackUrl : null,
    documentTemplate : null,
    errorUrl : null,
    fanout : {
      enabled : false,
      rootPath : "/data/item",
      itemType : "document"
    },
    inputBufferSize : 65536,
    keepInputForSeconds : 86400,
    outputType : null,
    transform : null,
    transformBefore : null,
    uploadUrl : null
}

Webhook Configuration

uploadUrl

Optional URI to send error events to.

• Data Type: fully qualified URI string
• Default: null
• Can be overridden by REST API query parameter: error (e.g. POST /renderpdf?upload=https://on.upload/do/something).
• If uploadUrl is neither set as query parameter nor in the config then the upload step is not triggered for the job at hand.

Additional Hints

• You can provide more than one URI in the uploadUrl if separated by whitespace.
  • Multiple URIs will be processed sequentially in the given order.
• Details of the upload request (request method, headers, bodies) must be configured in /upload/config.ion.

callbackUrl

Optional URI to send callback events to.

• Data Type: fully qualified URI string
• Default: null
• Can be overridden by REST API query parameter: callback (e.g. POST /renderpdf?callback=https://on.callback/do/something).
• If callbackUrl is neither set as query parameter nor in the config then the callback step is not triggered for the job at hand.

Additional Hints

• You can provide more than one URI in the callbackUrl if separated by whitespace.
  • Multiple URIs will be processed sequentially in the given order.
• Details of the callback request (request method, headers, bodies) must be configured in /callback/config.ion.

errorUrl

Optional URI to send error events to.

• Data Type: fully qualified URI string
• Default: null
• Can be overridden by REST API query parameter: error (e.g. POST /renderpdf?error=https://on.error/do/something).
• If errorUrl is neither set as query parameter nor in the config then the error step is not triggered for the job at hand.

Additional Hints

• You can provide more than one URI in the errorUrl if separated by whitespace.
  • Multiple URIs will be processed sequentially in the given order.
• Details of the error request (request method, headers, bodies) must be configured in /error/config.ion.

Fanout Configuration

fanout

Optional configuration object for fanout.

Controls whether XML input stream will be split into several parts each representing one rendering request.

• Data Type: Object
• Default: Fanout object with "enabled" set to false.
• Fanout configuration can NOT be overridden via query parameters in the REST API.

If fanout enabled is set to true then the incoming XML data is split at rootPath elements where the type attribute matches the value of itemType.

fanout.enabled

Optional switch to enable fanout processing.

• Data Type: boolean
• Default: false

fanout.rootPath

Optional path expression to identify elements within the XML stream that may start new job data items. This is not XPath but s simple concatenation of the local names of the elements.

• Data Type: String
• Default: /data/item

fanout.itemType

Optional value of the XML attribute named type. Only elements matching the rootPath AND having a type attribute will be regarded as beginnings of new job data items.

• Data Type: String
• Default: document

fanout.itemAttribute

Optional value of the XML attribute name. Attribute name defaults to type. To skip attribute matching completely set the itemAttribute to en empty string.

• Data Type: String
• Default: type

Aggregate Configuration

aggregate

Optional configuration object for aggregate.

Controls whether a second "aggregate" phase is appended to the normal processing of fanout items.

Requires fanout.enabled to be true.

• Data Type: Object
• Default: Aggregate object with "enabled" set to false.
• Aggregate configuration can NOT be overridden via query parameters in the REST API.

aggregate.enabled

Optional switch to enable aggregate processing.

• Data Type: boolean
• Default: false

aggregate.timeoutInSeconds

Optional maximum duration between splitting the fanout input and start of the aggregate rendering. The actual time will depend on the current load of the service. An aggregate ticket will be created and enqueued immediately after all fanout tickets are successfully completed.

Recommendation: Keep identical with the keepOutputForSeconds property in the corresponding renderpdf/config.ion for fanout.

• Data Type: Integer
• Default: 1800 // 30 min
• Maximum: 21600 // 6 hours

Transformation Configuration

transform

Optional name of an XSL stylesheet to be applied to the XML input before sending it to rendering.

The stylesheet must be stored in an xslt subfolder like this /{project}/transform/xslt/mystylesheet.xslt.

• Data Type: String
  • currently, only file name of an XSL stylesheet are supported
  • names must follow the regex pattern ^\w+\.xslt$
• Default: null
• Can be overridden by REST API query parameter: transform (e.g. POST /renderpdf?transform=fancystuff.xslt).
• If transform is neither set as query parameter nor in the config then the transform step is not triggered for the job at hand.

transformBefore

Optional name of an XSL stylesheet to be applied to the XML input before applying the fanout split.

The stylesheet must be stored in an xslt subfolder like this /{project}/transform/xslt/mystylesheet.xslt.

• Data Type: String
  • currently, only file name of an XSL stylesheet are supported
  • names must follow the regex pattern ^\w+\.xslt$
• Default: null
• Can be overridden by REST API query parameter: transformBefore (e.g. POST /renderpdf?transformBefore=fancystuff.xslt).
• If transformBefore is neither set as query parameter nor in the config then the transform step is not triggered for the job at hand.

Miscellaneous Configuration

documentTemplate

Optional name of the document template for the comet_pdf process during renderpdf stage.

• Data Type: String
• Default: null
• Can be overridden by REST API query parameter: documentTemplate (e.g. POST /renderpdf?documentTemplate=foobar).
• If documentTemplate is neither set as query parameter nor in the config then nor in the /renderpdf/config.ion then renderpdf step will use the default build process of comet_pdf.

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).

Additional Hints

• This property takes precedence over the property in /renderpdf/config.ion with the same name documentTemplate.

keepInputForSeconds

Maximum duration that input data from the request body are cached in a backend blob storage.

WARNING! Do not change this property unless you exactly know what you are doing.

• Input is cached if it is in application/zip format or if it exceeds the inputBufferSize threshold.
• Data Type: int
• Default: 86400 (1 day)
• Range: min=60, max=86400 (i.e. between 1 min and 1 day)

inputBufferSize

Optional maximum size of input data from the request body that fits into one message. Larger inputs are cached in a backend blob storage.

WARNING! Do not change this property unless you exactly know what you are doing.

• Input is always cached if it is in application/zip format.
• Data Type: int
• Default: 65536 (64 KB)
• Range: min=65536, max=4194304 (i.e. between 64 KB and 4 MB)

outputType

Optional type of the rendering output. Currently, the only supported value is pdf.

WARNING! This property is only used when using the endpoint POST /render instead of POST /renderpdf. Use of this endpoint is discouraged. The feature may be deprecated and removed in later versions.

• Data Type: String
• Default: pdf
• Corresponds to REST API query parameter: outputType in calls to POST /render

Image Output Configuration

convert

Optional name for pdf to image conversion (matrix style), like 'f=jpg;r=300;p=1'.

• Data Type: String
• Default: null
• Can be overridden by REST API query parameter: convert (e.g. POST /renderpdf?convert=f=png;r=72;p=1).
• If convert is neither set as query parameter nor in the config then nor in the /restapi/config.ion then renderpdf step will use the default build process of comet_pdf.

Options will be:

Option	Short	Default	Possible values	Required	Comments
format	f		'png', 'jpg'	mandatory	in case of an unsupported value an error is thrown
resolution	r	150	DPI - integer between 1 (min) and xxxx (max)	optional	in case of invalid values the system falls back to the default
page	p	1	integer	optional	if page does not exist an error is thrown; this implies 'image/*' as storage and delivery format
pageset	ps	null	'all', '1-3,5,7-9', '3-n'	optional	takes precedence over 'page'; this implies 'application/zip' as storage and delivery format; only existing pages are converted; non-existing pages do not lead to an error, 'n' means 'last page'
quality	q	75	JPEG quality - integer between 0=low and 100=high	optional	in case of invalid values the system falls back to the default
app	a	poppler	poppler	optional	undocumented option for later use if we support further ways of conversion

This list can later be extended by things like rx=150;ry=200, width=640;height=480, crop=40,40,120,220 or rotate=90 etc.

Example for the configuration

// restapi/config.ion
{
  convert: "f=png;ps=1-3;r=300" // as matrix parameter
  // convert: "f=png;ps=1-3;r=300 rotate=90" // for a pipeline
}