RenderTasks - extending Cinnamon with external tools

A RenderTask is a task that is started explicitly by the user or triggered automatically during a workflow. It will be run as an external program, that connects to the Cinnamon server and performs actions in the user's name.

Input

The RenderServer searches for OSDs with object type "_render_task" and prostate "waiting". For each object found, it calls the RenderTask (your program) with the two command line parameters:

1. cinnamonObjectId - the id of a task object in a Cinnamon repository (always a number)
   
2. repository - the name of a Cinnamon repository

Connect to the server

With the two parameters, your program connects to the server. The Cinnamon server currently offers a multitude of API methods over HTTP which expect their input to be HTML-form-encoded POSTs. The initial connection will be a call to the "connect" method, which requires your program to have the credentials of a valid user account. It is best to create a separate renderTask user with broad read but limited write privileges.

The result of the call to "connect" is a session ticket, which is required for all further API method calls.

The task object

With the valid session ticket, you can call getObject(cinnamonObjectId) and retrieve the XML representation of the task object, which holds further input parameters. Via getMeta(cinnamonObjectId), you can fetch those parameters as XML.

<meta>
  ...
  <metaset type="render_input">
    ... 
    <sourceId>id of a source object</sourceId>
    <renderTaskName>Your task's name</renderTaskName>  
  </metaset>
  <metaset type="render_output">
    ...
  </metaset>
</meta

The /metaset[@type='render_input'] element contains specific input for your render task - renderTaskName is required by the RenderServer, all other elements are dependent on your program's needs. (Which means that you have to configure or change the user's client to set those additional parameters). For example, the foo2pdf demo implementation requires a sourceId of a single object which it will render to PDF.

Perform the task

With the input from the render_input metaset, your program should be able to perform its tasks, for example you can now download the content of any dependencies and transform or render them to the desired format. If something goes wrong, use sudo (see below) and add <error>message</error> to the render_output metaset element and set the object's procstate field to "failed" in case of a permanent problem:

<meta>
  ...
  <metaset type="render_output">
    <error>Could not find object with id 53341</error>
  </metaset>
</meta>

Sudo to save messages and upload data

In order to write status updates to the render_output element or upload a new rendition to the repository, the renderTask-user will need the required permissions (that is, read/write access) to the objects it wants to change or create. Provided that the renderTask user has been configured to have sudo-capability, it should now call the sudo API method and receive a new session ticket. The sudo method expects a user_id parameter - we  recommend that you make changes in the name of the render task object's owner. Note: if you need an audit trail, you will have to configure logging of the Cinnamon server to capture the work done in the name of the task owner.