wiki:FactoryManual/FromScratch

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

--

Factory Manual: 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 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.

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(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 (string)
A three-letter code indicating the file format of the file (odt, ods, odp).
document (string)
The base64-encoded contents of the file.

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.

Examples

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>

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>

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>