Quickstart

When starting with a new priint rendering project several topics must be worked on:

• Designing Input Data Format
• Planning Image Handling
• Creating Comet XML Project
• Configuring REST API defaults
• Configuring PDF Upload
• Configuring Notifications
• Triggering a Rendering
• Receiving Rendering Results

Designing Input Data Format

priint:cloud rendering service transforms XML into PDF documents.

Input data must be in a defined XML format (data.xml) that suites the comet xml project.

The format is very simple and versatile but is finally restricted by the specific comet xml project.

priint:cloud rendering projects only use a subset of the full format.

A detailed description of the full format is given here.

An Example

Example of content data

<data lang="de">
  <item type="product" id="0815" label="Meine neue Bierdose">
    <item type="article" idref="0815-721-LTS" />
  </item>
  <item type="article" id="0815-721-LTS" label="Langzeit Bierdose" >
    <item key="description" content="Langlebige Bierdose mit Support" />
    <item key="image" url="https://my.mam/images/hi7w834ikd_bierdose.png" />
  </item>
</data>

The example shows a typically referenced data structure.

Although the XML schema also allows for deeply nested documents, most comet xml projects prefer an approach akin to relational databases. This is defined by typed items (like rows in a database table), list of referenced children (through idref attributes) and simple key-value properties, where keys can occur multiple times.

The specific comet xml project relates to the data.xml through the xmlquery or xpath statements in its placeholders.

Here comes an example list of placeholder with XPath expressions. The question mark ? is replaced by the actual StringID in the placeholder implementation. Here is only serves documentation purpose:

No	Placeholder	XPath
100001	product_id	/data/item[@type='product' and @id=?]/@id
100002	product_title	/data/item[@type='product' and @id=?]/@label
100011	article_id	/data/item[@type='article' and @id=?]/@id
100012	article_title	/data/item[@type='article' and @id=?]/@label
100012	article_descr	/data/item[@type='article' and @id=?]/item[@key='description']/@content
100012	article_picto	/data/item[@type='article' and @id=?]/item[@key='image']/@url

In this step you have to decide

• how to generate the XML data from your data source
• what to include into the XML and what to exclude from it
• where to transform into the final data.xml structure

Planning Image Handling

PDFs embed images. In priint:cloud you have three main options to provide images to the rendering process:

• publicly available image URLs (like the one in the example above). Images will be downloaded during rendering.
• images as part of the comet xml project (aka 'static images')
• images send together with the data.xml in a zip file as request body to the /renderpdf endpoint

Providing image URLs as part of the XML input data is the most obvious and commonly used variant. This has some consequences:

• Images must be available in public internet
• Images will probably be protected by some security method (BasicAuth, OAuth2, etc.)
• Images are downloaded by the mediaproxy. This requires some configuration. See Media Proxy Integration
• Image download can have a huge impact of the rendering time. Slow media asset server lead to slow PDF generation.

See for Handling Images more detail.

Creating Comet XML Project

The comet xml project is a set of configuration files in XML format plus some template files in w2ml format and some internal Comet script files (either python or cscript).

comet xml projects are created through the management application and edited locally via the priint comet tools extension in Visual Studio Code.

For details on comet xml projects see Comet and Management.

Configuring REST API defaults

See restapi configuration

Add Configuration to Run the Comet Project in the Cloud

See renderpdf configuration

Configuring PDF Upload

For the recommended Asynchronous flow with upload you need to edit some configuration files: namely /restapi/config.ion and /upload/config.ion. Details are given in Uploading PDFs to Destination Servers.

Configuring Notifications

For the recommended Asynchronous flow with upload you need to edit some configuration files: namely /restapi/config.ion and /upload/config.ion. Details are given in Uploading PDFs to Destination Servers.

Triggering a Rendering

Renderings are requested by an HTTP POST of the following kind.

Rendering request example (async)

POST /rest/tenants/{tenant}/projects/{project}/renderpdf
Host: api.priintcloud.com
Authorization: Bearer {access_token} 
Content-Type: application/xml
Accept: application/json

<data>...</data>

Rendering response example

202 Accepted
Content-Type: application/json

{ "tickets": ["{ticketId}"] }

• Authorization requires a valid JWT token that can be acquired as given in the section below.
• Payload is of type application/xml. It must follow the data.xml schema as described above.
• On success the service responds with status "202 Accepted" and a JSON body listing the internal ticket id.

For details see Rendering Service

Receiving Rendering Results

PDFs can be received in two different ways: Either with an "upload" or with a "callback & download". Both represent a type of webhook. In the "upload" case the PDF is already part of the webhook payload. In the "callback & download" case the webhook payload only contains the download URI for the PDF which can then be used to retrieve the PDF in a call initiated by the webhook consumer.