wiki:FactoryManual/NewBackends

Version 1 (modified by sander, 8 years ago) (diff)

--

Creating new backends

Creating new backends for Officeshots.org is not very hard if you know how to interface with the application that you want to support and know how to program Python. You will need a copy the standard factory.

Basic backend implementation

Start off by creating a new file in the backends directory. The filename should match the name of your backend in lowercase. In that file create a new class derived from backends.Backend and implement the process() method. This method is handed a single variable called job which contains the information returned from the jobs.poll() XML-RPC call. It's a dictionary that contains the following keys.

The most up-to-date version of the XML-RPC API documentation can be found by browsing to the XML-RPC end-point itself. Officeshots.org distinguishes between browsers and XML-RPC clients. If you visit the XML-RPC endpoint http://www.officeshots.org/xmlrpc using your browser then you will be shown the most up-to-date documentation generated directly from the PHP source code.

job (string)
The GUID of the job.
application (string)
The name of the application this job needs to be processed by.
version (string)
The version string of the application.
pageStart (int)
The first page of the doucment to render in the output. Supporting this feature is optional.
pageEnd (int)
The last page of the document to render. If this is zero then all the pages starting from pageStart should be rendered. Supporting this feature is optional.
format (string)
A three letter code indicating the desired output format (pdf, png, odf). If this is empty then you may choose the output format yourself.
filename (string)
The original filename of the document as it was uploaded by the user.
doctype
A three-letter code indicating the file format of the file (odt, ods, odp).
document (string)
The base64-encoded contents of the file.

You can process the incoming job any way you like. The base Backend class does provide a series of useful functions to assist you, for example to decode and store the document to a temporary file or to open and base64-encode files from the temporary directory. For a full description of these functions, please see the complete API reference at http://docs.officeshots.org/factory.

The process() function must return a tuple of (format, contents) where doctype is a three letter code indicating the format of your output (e.g. odf, png or pdf) and contents is the base64-encoded contents of the result.

Handling errors

If for any reason your backend cannot correctly process the document then you should throw a BackendException or a subclass thereof. The BackendException takes two parameters: the exception message and a boolean that indicates whether the exception is recoverable. If you set the second parameter to False (the default) then your backend will be removed from the list of active backends. If you set the recoverable parameter to True then the job will be aborted but your backend will still receive new jobs in the future.

Initialization and configuration

If you need to do any initialization or read extra configuration variables then you can override the initialize() method. The commandline options of the factory are available in the self.options dictionary. The configuration file is available as a ConfigParser instance on self.config. The variable self.section contains the name of the section that contains the configuration options for your backend.

If you want to abort the initialization then you should trow a BackendException.

Submitting your backend

If you want your backend to be included in the standard Officeshots.org backend distribution, please send us patches on the mailinglist.