Officeshots.org Factory Manual

Sander Marechal

Lone Wolves Foundation

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License (GFDL), Version 1.3 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.

Permission is also granted to copy, distribute and/or modify this document under the terms of the GNU General Public License (GPL), Version 3 or any later version published by the Free Software Foundation.

DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT ARE PROVIDED UNDER THE TERMS OF THE GNU FREE DOCUMENTATION LICENSE WITH THE FURTHER UNDERSTANDING THAT:

  1. DOCUMENT IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, WARRANTIES THAT THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT IS FREE OF DEFECTS MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE OR NON-INFRINGING. THE ENTIRE RISK AS TO THE QUALITY, ACCURACY, AND PERFORMANCE OF THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT IS WITH YOU. SHOULD ANY DOCUMENT OR MODIFIED VERSION PROVE DEFECTIVE IN ANY RESPECT, YOU (NOT THE INITIAL WRITER, AUTHOR OR ANY CONTRIBUTOR) ASSUME THE COST OF ANY NECESSARY SERVICING, REPAIR OR CORRECTION. THIS DISCLAIMER OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF THIS LICENSE. NO USE OF ANY DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT IS AUTHORIZED HEREUNDER EXCEPT UNDER THIS DISCLAIMER; AND

  2. UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, WHETHER IN TORT (INCLUDING NEGLIGENCE), CONTRACT, OR OTHERWISE, SHALL THE AUTHOR, INITIAL WRITER, ANY CONTRIBUTOR, OR ANY DISTRIBUTOR OF THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT, OR ANY SUPPLIER OF ANY OF SUCH PARTIES, BE LIABLE TO ANY PERSON FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER DAMAGES OR LOSSES ARISING OUT OF OR RELATING TO USE OF THE DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT, EVEN IF SUCH PARTY SHALL HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES.


Table of Contents

Introduction
1. Quickstart
2. Setting up your account
2.1. About SSL cerificates
2.1.1. Get an SSL Certificate from CACert
2.1.2. Export your SSL Certificate from your browser
2.2. Configuring your factory
3. Using the standard factory
3.1. Downloading and installing the standard factory
3.2. Configuring backends
3.2.1. OOOServer
3.2.2. CLI
3.3. Running the standard factory
4. Creating new backends
4.1. Basic backend implementation
4.2. Handling errors
4.3. Initialization and configuration
4.4. Submitting your backend
5. Building a factory from scratch
5.1. jobs.poll()
5.1.1. Job locking
5.1.2. Examples
5.2. jobs.finish()
5.2.1. Examples
6. References

List of Examples

3.1. Example configuration
5.1. Calling jobs.poll()
5.2. Response to jobs.poll() containing a job
5.3. Response to jobs.poll() when there are no jobs
5.4. Calling to jobs.finish()
5.5. Response to jobs.finish()

Introduction

Officeshots.org is a distributed application where users can upload office documents and check how they are rendered, printed and saved by different office applications. Officeshots.org consists of a single central server where documents are uploaded and distributed to clients (called factories) which do the actual work of taking screenshots, printing documents or saving them.

This document is intended for people who want to run the standard factory or implement their own factory using the available XML-RPC API.

Chapter 1. Quickstart

For the impatient, here follows a quick rundown of the steps that you need to do in order to run your own Officeshots factory for OpenOffice.org on Linux or Windows.

  1. Register for an account on the Officeshots website, activate your acount and let us know that you want to run a factory. See Chapter 2, Setting up your account.

  2. Get an SSL client certificate if you do not have one yet. See Section 2.1.1, “Get an SSL Certificate from CACert”.

  3. Log in on the Officeshots website, create a new factory, give it a nice name and add application workers to it. Add OpenOffice.org Calc, Impress and Writer separately. See Section 2.2, “Configuring your factory”. Linux users, please check if you need to add OpenOffice.org or Go-OO.

  4. Install OpenOffice.org, Python and the Python UNO bridge. Windows users need Python 2.6 and can find the UNO bridge when the choose Custom install when installing OpenOffice.org. Linux users will want to install the Python M2Crypto library as well.

  5. Download the latest Officeshots factory using Subversion. If you do not have Subversion then you can download a tar.gz package, but Subversion is better.

    					$> svn checkout http://code.officeshots.org/officeshots/trunk/factory
    				
  6. Copy conf/config.default.ini to conf/config.ini. Set the correct path for your SSL key and certificate file. Linux users should make sure that log_file is writeable or change the path. Windows users should set transport to pyssl and set correct paths for log_file and tmp_files. See Section 3.2, “Configuring backends”.

  7. In the oooserver- sections, check that the version number is correct. Windows users should also remove the ooo_host and ooo_port options and uncomment the ooo_pipe option. See Section 3.2.1, “OOOServer”.

  8. Start OpenOffice.org in headless mode. Linux users can execute:

    					$> soffice -headless -nologo -norestore -accept=socket,host=localhost,port=8100;urp;StarOffice.ServiceManager
    				

    Windows users should edit utils/oooserver.bat and run that file. See Section 3.2.1.1, “Running OpenOffice.org in headless mode”.

  9. Start the factory. On Linux, simply run the src/factory.py script. On windows, edit utils/ooofactory.bat and execute it. See Section 3.3, “Running the standard factory”.

After all that, your factory should be up and running. If it does not, please read the remaining chapters of this manual or ask us for help on the Officeshots mailinglist.

Chapter 2. Setting up your account

If you want to run a factory then you will first need to create an account at the central server and set it up properly. You can register yourself at the Officeshots.org website. Once you have done so you can either login using the login form or you can use an SSL client certificate and use the secure website. After your registration you will need to contact the Officeshots.org staff and tell them that you want to run a factory. They will probably ask you a couple of questions to verify a few things and then enable your account to use factories.

2.1. About SSL cerificates

SSL certificates are optional for using the central Officeshots.org website but mandatory if you want to use the XML-RPC API. You can use any client SSL certificate signed by any well known Certificate Authority as long as your certificate's Common Name contains the same e-mail address as you have used to register your account with. If necessary you can change your account e-mail address to match the one on your certificate.

[Note]Note

Due to a bug in Apache mod_gnutls, the development server currently only accepts client certificates that are signed by CACert.

2.1.1. Get an SSL Certificate from CACert

If you do not have an SSL client certificate then you can easily get one for free from CACert. Go to the website of CACert and register for an account. When you have an account, login and in the menu go to Client Certificates. Create a new certificate and make sure you add your e-mail address to it. When CACert has created a certificate for you then you can import it in your browser by clicking a link.

Your certificate is now in your browser. If you want, you can use it to automatically login to the officeshots website. To do that, visit https://www.officeshots.org.

2.1.2. Export your SSL Certificate from your browser

If you want to run a factory then you need to export your certificate from your browser and convert it into PEM format which our factory understands. In Firefox, to to Preferences, Advanced, View Certificates, Your Certificates. Click on your certificate and click Backup. You will be asked to create a password to protect your certificate. Thawte has instructions for Internet Explorer.

You now have a .p12 or a .pfx file with your certificate. The last step is to convert this to PEM format. You can do this with OpenSSL. Linux systems usually have this installed. Windows users will need to install OpenSSL themselves or ask a friend who uses Linux to convert the certificate for them. The command to convert the certificate is:

					$> openssl pkcs12 -in certificate.p12 -out certificate.pem -clcerts
				

You will be asked to enter your backup password to read the .p12 or .pfx file and create a new password to encrypt the PEM file. Alternatively, if you do not want to encrypt the PEM file then you can use the following command.

					$> openssl pkcs12 -in certificate.p12 -out certificate.pem -clcerts -nodes
				

Using an unencrypted PEM file is not as safe. If you have the M2Crypto python library on your computer then you can use an encrypted PEM file. If you do not have M2Crypto then you will need an unencrypted PEM file because the standard Python SSL library cannot remember your password for you.

2.2. Configuring your factory

After the Officeshots.org staff have enabled your account for factory usage you can add factories to your account. A factory is a single computer that you have that participates in Officeshots.org. If you want to supply a Windows XP machine, a Linux machine and a smartphone then you would create three factories. To create a new factory, go to the Officeshots website and in the menu click Factories and then Add another factory. Then pick a name for it and fill in the hardware and operatingsystem fields.

Next you can start adding workers to your factory. A worker is a specific office application that runs on your factory. If your Linux machine has OpenOffice.org and Gnumeric installed then you would add four factories: OpenOffice.org Writer, OpenOffice.org Calc, OpenOffice.org Impress and Gnumeric. For every worker you need to select which office application it provides and the version number. The version number can be any string, such as 2.4 or 2003 SP2.

[Note]Note

If you run OpenOffice.org on Linux then you need to be careful which one you pick. Many distributions of Linux do not ship OpenOffice.org but Go-OO. Go-OO is a version of OpenOffice.org that is built by Novell and it is different from the standard OpenOffice.org. If you are running Ubuntu, Debian, Frugalware or Gentoo then you are running Go-OO and not OpenOffice.org. Please pick Go-OO in the application dropdown.

[Note]Note

In the future it will be possible to automatically configure your workers based on the local configuration file of your factory. For the moment you will need to create your workers manually on the Officeshots.org website. Make sure that the worker configuration on the website matches the worker configuration on your system or you will be given jobs by the central server that your factory cannot handle.

Chapter 3. Using the standard factory

This chapter details the installation and configuration of the standard factory that is distributed by Officeshots.org. If you are implementing your own factory from scratch you can skip this chapter, but if you want to develop a factory builds on the standard factory then you want to read this so you understand how configuration works.

3.1. Downloading and installing the standard factory

You can download the standard factory from our Subversion repository at http://code.officeshots.org/officeshots. You can also download a tar.gz package but it is easier to keep up-to-date when you download it from Subversion. Use the following command to download the latest version of the factory from Subversion:

				$> svn checkout http://code.officeshots.org/officeshots/trunk/factory
			

To update your factory to the latest version, go to the directory where the factory is and run:

				$> svn update
			

Next, copy conf/config.default.ini to conf/config.ini and open it in a text editor. Change the settings in the global section according to your preferences.

factory_name

The name of your factory. This must match the name of the factory that you created on the website. You can pick any name you like but all your factories must have a different name.

transport

Which SSL transport you want to use. Not all transports work on all platforms. Currently supported are m2crypto which requires the Python M2Crypto library, and pyssl which uses Python's built-in HTTPS connection. The default is currently mycrypto because it allows the use of PEM encrypted SSL client certificates.

log_file

The logfile that you want to log to.

[Note]Note

By default log_file is set to /var/log/officeshots.org. On most Unix/Linux systems you are not allowed to write to this directory with your normal account. You are strongly suggested to change this parameter.

log_level

Determines the verbosity of the log. Can be set to one of debug, info, warning, error or critical.

log_format

Determines the format of the log entries. Please see the Python documentation on logging for more detail.

xmlrpc_endpoint

The XML-RPC endpoint. This should normally be https://www.officeshots.org/xmlrpc

tls_certificate_file

A full path pointing to the file containing your PEM-encoded SSL/TLS certificate.

tls_key_file

Full path pointing to the file containing your PEM-encoded SSL/TLS private key. This can be the same file as your certificate.

load_max

The maximum system load. If the system load is greater than this value then the factory will sleep instead of poll for new jobs. This has currently no effect on Windows.

tmp_files

Path to a directory that will be used to store temporary files.

backends

A comma separated list of backends (applications) that are enabled. For every worker that you added to your factory on the server you should have a backend in your configuration file. See below for more information about backends.

3.2. Configuring backends

For every worker that you added to your factory on the Officeshots website you should have a backend in your configuration file. You can name the backends any way you like. Add them all to the backends in a comma separated list. Then, for all the backends in that list you need to have a separate configuration section. For example, if you added AbiWord and Gnumeric as workers on the Officeshots website then you need two backends in your configuration file.

Example 3.1. Example configuration


[Global]
backends = my_abiword, some_old_gnumeric

[my_abiword]
# Configuration options for AbiWord

[some_old_gnumeric]
# Configuration options for Gnumeric

				

If you do not want to use certain backends/sections then you only need to remove them from the backends line. You do not need to remove the entire sections. All the backends have at least a few configuration options in common.

application

The name of the application. This must be the same as the application name configured on the website.

version

The version number of the application, such as "3.0" or "2003 SP2".

doctypes

A comma separated list of doctypes codes that the application can handle, such as odt, ods or odp. This must be a subset of the doctypes that the application can handle according to the server. For example, OfficeReader can handle odt, ods and odp files. You can skip processing of presentations by configuring the backend to only accept odt and ods files.

[Note]Note

These are document type codes, not extensions. The document type codes are defined on the server. The odt code for example matches both odt (text) and ott (text template) files.

formats

A comma separated list of format codes that the application can process such as png, pdf or odf.

backend

The name of the Python backend class that implements the worker. See the next section on which backends are available.

Besides these standard configuration options each backend can have extra configuration options depending on the backend type.

3.2.1. OOOServer

The OOOServer backends implements OpenOffice.org running in headless mode. As such it is not able to produce screenshots but only ODF roundtrip and PDF export. To use the OOOServer backend you must have OpenOffice.org running in headless mode. See Section 3.2.1.1, “Running OpenOffice.org in headless mode”.

Besides the standard configuration options, you can set the following options for the OOOServer backend.

ooo_host

The hostname of the machine that OpenOffice.org is running on in headless mode. Normally this should be localhost. If you set this option then you should also set the ooo_port option.

ooo_port

The port number that OpenOffice.org is listening to. This should normally be 8100.

ooo_pipe

The name of the pipe that OpenOffice.org is listening to. If you set this option then you should not set the ooo_host and ooo_port options.

[Note]Note

On Windows XP and Vista it is not possible to connect to OpenOffice.org using a socket with the ooo_host and ooo_port options. You should use a pipe instead.

3.2.1.1. Running OpenOffice.org in headless mode

When OpenOffice.org is running in headless mode you cannot start it yourself anymore. The easiest thing to do is to create a new user on your computer and run OpenOffice.org in headless mode under that user account instead of your own. Linux users can start OpenOffice.org in headless mode using the following command:

						$> soffice -headless -nologo -norestore -accept=socket,host=localhost,port=8100;urp;StarOffice.ServiceManager
					

For Windows users there is a simple batch file in the utils directory called utils/oooserver.bat. Simply edit that file, make sure that the OOOPATH is correct and that the OOOPIPE is the same as the pipe name in your configuration file. Then double-click the file to start OpenOffice.org in headless mode. If you want to start OpenOffice.org manually on Windows then you can execute the following command:

						$> soffice.exe -headless -nologo -norestore "-accept=pipe,name=officeshots;urp;StarOffice.ServiceManager"
					
[Note]Note

Sometimes OpenOffice.org on Windows does not install the Python UNO bridge. You can re-install OpenOffice.org. Make sure you choose Custom install amd check the box that installs Python UNO.

3.2.1.1.1. OOOServer init script for Debian/Ubuntu

The oooserver init script in the utils directory can be used to automatically start and stop OpenOffice.org in headless mode on a Debian or Ubuntu machine. It uses xvbf, the X Virtual FrameBuffer so it can even run on a machine that has no complete X Server installed such as most servers. Place this file in your /etc/init.d directory and make it executable. Then you need to add symlinks to it in the appropriate places. You can execute the following command (as root) to create these symlinks automatically:

							#> update-rc.d oooserver defaults
						

You will also need to configure the oooserver init script. By default oooserver will run as user nobody but on many systems this user does not have a valid home directory. OpenOffice.org does not start without a valid home directory. Either make sure user nobody exists and has a valid home directory, or change the USER parameter in the oooserver init script.

3.2.2. CLI

The CLI backend implements a generic interface for applications that can convert documents using the commandline. You can find default configurations for applications that support this, like AbiWord, in the config.default.ini file.

Besides the standard configuration options, you need to set the following options for the CLI backend.

command

The command to execute. This command should generate a file on your computer containing the converted document. You can use various placeholders in this command. See Section 3.2.2.1, “CLI placeholders”.

result

Full path to the file that contains the converted document after the command has run. You can use various placeholders in this command. See Section 3.2.2.1, “CLI placeholders”.

default_format

The default format code to use if the user did not specify a desired output format.

3.2.2.1. CLI placeholders

You can use various placeholders in the command and result configuration options.

%source_path

The full path to the source file to convert. For example, /tmp/officeshots/test.odt.

%source_dir

The directory where the source file is located. Usually this is equal to the directory where Officeshots stores it's temporary files, for example /tmp/officeshots.

%source_file

The filename of the source file, for example test.odt.

%source_base

The basename of the source file. That is, the name without the extension. If the filename of the source file is test.odt then the basename would be test. At the moment, the CLI backend stores it's temprary files using the job unique ID as it's filename, so usually this value will be equal to the %jobid placeholder.

%source_ext

The filename extension of the source file. If the filename of the source file is test.odt then the extension would be odt.

%jobid

The unique ID (UUID) for the job that you are processing.

%format

The format code for this job. If the user did not request a specific fomat then this will be set to the default format that you configured. See also formats.

%jobid

The unique ID (UUID) for the job that you are processing.

%dest_ext

The default file extension that should be used for the result document.

%temp_dir

Path to the directory where Officeshots stores temporary files. For example /tmp/officeshots.

3.3. Running the standard factory

To run the standard factory, execute the src/factory.py script. There are a couple of extra commandline arguments that you can pass to this script.

--?, --h, --help

Show the help on the commandline options.

-c, --condig

Full path to the configuration file to use. By default conf/config.ini is used.

-d, --debug

Turn on debugging. When debugging is on the log_level will be set to debug, all log messages will appear on the console and all XML-RPC requests and responses will be echoed.

[Note]Note

If you are running OpenOffice.org on Windows then you must run the factory.py script with the Python version that was installed by OpenOffice.org. The Python UNO bridge does not work with any other version of Python on Windows. However, you do need the other libraries from the standard Python since the OpenOffice.org version of Python does not understand SSL connections.

To make this easier for Windows users, there is a script called utils/ooofactory.bat that automatically starts the factory with the correct Python versions and libraries. Make sure you have Python 2.6 installed. Then edit the ooofactory.bat script and make sure that the paths to Python 2.6 and OpenOffice.org are correct. The double-click the file to start the factory.

Chapter 4. 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. See Section 3.1, “Downloading and installing the standard factory”.

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

[Note]Note

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://dev.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.

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

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

4.4. 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: http://dev.officeshots.org/users/register.

In order to be included you do not only need to build your backend but also provide documentation about it, so please submit patches for this document as well.

Chapter 5. Building a factory from scratch

If you cannot build on the existing Python factory implementation then you can also interface directly with the XML-RPC API of Officeshots.org.

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://dev.officeshots.org/xmlrpc using your browser then you will be shown the most up-to-date documentation generated directly from the PHP source code.

Before you can use the API you need to have an account on the server and an SSL certificate to match. See Chapter 2, Setting up your account. You will also need an XML-RPC client that can authenticate using SSL client certificates. The API itself is straight forward. Simply call jobs.poll() to get jobs from the server and call jobs.finish() to upload the processed results. There is currently no need to report errors back to the server. The job will simply time out after a few minutes and handed to a different factory by the central server.

5.1. jobs.poll()

You start using the API by calling jobs.poll. The first time you call this function will activate your factory on the server. That means that the applications associated with your factory will be shown on the front page of the Officeshots website. By default, only factories that have been active (i.e. called the jobs.poll function) will be shown on the front page. The signature is as follows.

struct jobs.poll(factory_name); 
string  factory_name;

When there are no suitable jobs waiting on the server then an empty value will be returned. If there are jobs then you will get a struct containing nine members.

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.

5.1.1. Job locking

When a job is returned to you it will be locked for five mintues. That means the job will not be sent to any other factory that could handle the job. This lock expires automatically. If you take longer than five minutes to process the job then it is possible that it has been sent to a different factory. In that case your upload using jobs.finish will fail.

5.1.2. Examples

Example 5.1. Calling jobs.poll()


POST /xmlrpc HTTP/1.0
Host: www.officeshots.org
Content-Type: text/xml
Content-Length: 163

<?xml version='1.0'?>
<methodCall>
  <methodName>jobs.poll</methodName>
  <params>
    <param><value><string>My factory</string></value></param>
  </params>
</methodCall>

					

Example 5.2. Response to jobs.poll() containing a job


HTTP/1.1 200 OK
Date: Fri, 15 May 2009 12:06:12 GMT
Server: Apache/2.2.9 (Debian)
X-Powered-By: PHP/5.2.6-1+lenny3
Set-Cookie: CAKEPHP=1234567890ABCDEF; path=/; secure
P3P: CP="NOI ADM DEV PSAi COM NAV OUR OTRo STP IND DEM"
Connection: close
Content-Type: application/xml

<?xml version="1.0" encoding="iso-8859-1"?>
<methodResponse>
  <params>
    <param>
      <value>
        <struct>
          <member>
            <name>job</name>
            <value><string>4975c9c6-79a0-43a1-8134-0ba5c0a80105</string></value>
          </member>
          <member>
            <name>application</name>
            <value><string>OpenOffice.org Writer</string></value>
          </member>
          <member>
            <name>version</name>
            <value><string>3.0</string></value>
          </member>
          <member>
            <name>pageStart</name>
            <value><string>1</string></value>
          </member>
          <member>
            <name>pageEnd</name>
            <value><string>0</string></value>
          </member>
          <member>
            <name>format</name>
            <value><string>pdf</string></value>
          </member>
          <member>
            <name>filename</name>
            <value><string>mydocument.odt</string></value>
          </member>
          <member>
            <name>doctype</name>
            <value><string>odt</string></value>
          </member>
          <member>
            <name>document</name>
            <value><string>UEsDBBQA ... AAAAAA==</string></value>
          </member>
        </struct>
      </value>
    <param>
  </params>
</methodResponse>

					

Example 5.3. Response to jobs.poll() when there are no jobs


HTTP/1.1 200 OK
Date: Fri, 15 May 2009 12:06:12 GMT
Server: Apache/2.2.9 (Debian)
X-Powered-By: PHP/5.2.6-1+lenny3
Set-Cookie: CAKEPHP=1234567890ABCDEF; path=/; secure
P3P: CP="NOI ADM DEV PSAi COM NAV OUR OTRo STP IND DEM"
Connection: close
Content-Type: application/xml

<?xml version="1.0" encoding="iso-8859-1"?>
<methodResponse>
  <params>
    <param>
      <value>
      </value>
    <param>
  </params>
</methodResponse>

					

5.2. jobs.finish()

When you have converted the document that you recieved from the jobs.poll call then you need to upload it using jobs.finish. The signature is as follows.

string jobs.finish(factory_name,  
 job_id,  
 output_format,  
 data); 
string  factory_name;
string  job_id;
string  output_format;
string  data;

5.2.1. Examples

Example 5.4. Calling to jobs.finish()


POST /xmlrpc HTTP/1.0
Host: www.officeshots.org
Content-Type: text/xml
Content-Length: 163

<?xml version='1.0'?>
<methodCall>
  <methodName>jobs.finish</methodName>
  <params>
    <param><value><string>My factory</string></value></param>
    <param><value><string>4975c9c6-79a0-43a1-8134-0ba5c0a80105</string></value></param>
    <param><value><string>pdf</string></value></param>
    <params><value><string>UEsDBBQA ... AAAAAA==</string></value></params>
  </params>
</methodCall>

					

Example 5.5. Response to jobs.finish()


HTTP/1.1 200 OK
Date: Fri, 15 May 2009 12:06:12 GMT
Server: Apache/2.2.9 (Debian)
X-Powered-By: PHP/5.2.6-1+lenny3
Set-Cookie: CAKEPHP=1234567890ABCDEF; path=/; secure
P3P: CP="NOI ADM DEV PSAi COM NAV OUR OTRo STP IND DEM"
Connection: close
Content-Type: application/xml

<?xml version="1.0" encoding="iso-8859-1"?>
<methodResponse>
  <params>
    <param><value><string>497d9737-a2cc-4682-9d90-0136c0a80105</string></value></param>
  </params>
</methodResponse>

					

Chapter 6. References