[ODFPlugtest] ODF Plugfest - accounts for officeshots.org

[Preparation for ODF Plugfest and other plugtesting activities]

Dear participants,


in order to make your applications available through Officeshots.org
prior to the workshop, we have given all participants access to the
closed beta. For that we have used the mail account that you receive
this email on. If you want us to add other mail accounts as well, let
us know.e 

You will find a concise manual below. A more detailed manual can be
found on the site:

http://docs.officeshots.org/factory-guide/factory.html

Currently there are three possibltypes of output that are included:
print/pdf, screen output (if available) and code round tripping (i.e.
the ODF that you application returns after merely importing it to its
internal memory model and saving it). Please add the relevant
functionality to Officeshots - so if your application doesn´t have a
gui or print capability, you will just add ODF roundtripping. 

We are ready to help you to make possible way. If you have any
questions, please let us know so that your application can be tested
against in the most optimal way.

Kind regards, 
on behalf of the organisers,

Fabrice Mous                            
NOiV / ICTU
+31 648 58 51 62 

Michiel Leenaars 
OpenDoc Society
+31 6 27050947

---------------------------------------------------------
Getting applications into Officeshots.org

The first thing you should do is read our factory manual [1],
specifically chapters 1, 2 and 3. They explain in more detail what the
rest of this concise manual tells you.

[1] http://docs.officeshots.org/factory-guide/factory.html

Overview
--------
Officeshots works pretty simply. Someone uploads a document to our
website. These are distributed to a number of factories, i.e. regular
applications together with a wrapper that downloads these documents and
feeds them to the application - and returns them in the appropriate
format. Then these are uploaded again to our website and the user
who uploaded the document can download the conversions. This way people
can test interoperability without you having to share your application,
and without them having to run the software (which may have platform
requirements or dependencies that are hard to fulfill)

Things you need to do
---------------------

You will need an account on our website. At the moment Officeshots is in
closed beta. We have added all participants to the plugfest to the
whitelist of people that are allowed to register new accounts. If you
want to use a different e-mail address to register, please let us know
so that we can add it to the whitelist.

Then register at www.officeshots.org and optionally on
dev.officeshots.org as well (that's our development server, used for
testing new versions of the website and to let people such as yourself
safely test their factories). Let us know when you have created these
accounts because we may need to give you additional rights to use the
factory and API.

You will also need to tell us the correct application names for you
products (if they are not yet included) so that we can add them to the
website. If your application uses separate applications (like Microsoft
Word, Microsoft Excel and Microsoft Powerpoint are separate) then we
want the separate application names for ODT, ODS and ODP files. If you
use a single application (like IBM Symphony is) then we need just that
name.

In an ideal case you have the last major release of your tool(s) and
the latest development build within Officeshots.org. This will allow
everyone to test against the most relevant versions of your software. 
  
If you run your Officeshots.org client from the laptop you are taking
to the plugfest as well, or have a remote machine on which you can you
recompile with patches for this purpose, you can easily provide new
versions as you debug during the event. 

Next, you need an SSL client certificate. The factory manual chapter 2.1
explains how you can get such a certificate for free from CACert. If you
already have a certificate from another provider (e.g. Thawte or
Verisign) then you can use that as well. If you run on Windows you want
to export your certificate unencrypted.

Next configure your factory. You need to do this on the website
(Chapter 2.2). Later, you will have to configure your factory (most
likely in the factory config file - Chapter 3.1 and 3.2); these
configurations need to be the same. 


How to integrate
================

There are basically two ways to integrate your application with
Officeshots. Either you can (help us) write the code to do this and
integrate this with the standard factory program that other people
download and run for us. This is the way we prefer because it means
that everyone, and not just you, can help out with rendering your
documents. This is how most office suites are currently supported (like
OpenOffice.org, Gnumeric, etcetera).

The other way is that instead of improving our standard factory, you
develop your own in-house client and speak directly to the API at
www.officeshots.org. In that case you download the documents, convert
them and upload the results. Other people cannot do the same because
only you have the code. AbiWord does this for example. They have written
a special interface to connect the API at www.officeshots.org with the
rendering farm they run at abicollab.net.

Note that AbiWord has both kinds. They run their own custom client
on their own abicollab.net rendering farm, and there is support for
AbiWord in the standard factory that people can download and use with
the AbiWord that is installed on their own computer.

Integrating in the standard client (method 1)
---------------------------------------------

Our standard factory client is written in Python and runs on Linux/BSD,
Windows, MacOSX (untested), Symbian and many other platforms. You can
find the complete manual online [1]. This factory connects to
www.officeshots.org, downloads the documents and then calls a backend
module to do the actual rendering [2]. Which backends are available
varies from person to person depending of what applications they have
installed of course.

[1] http://docs.officeshots.org/factory-guide/factory.html
[2] http://docs.officeshots.org/factory/

Install Python 2.5 or 2.6 and download our factory. See Chapter 3.1 for
the correct locations to download.  

Now you can configure your factory. Use the factory config file
(Chapter 3.1 and 3.2). The configuration need to be the same as in the
web application. The example configuration file in the factory has some
example entries for applications that are controlled using the
commandline, so you can use those entries as an example to write the
configuration settings you need to make your application work. 

After all this you can start to test your factory. It may help you to
run the factory.py file with the -d flag. This turns on extra debugging
and prints all messages to the commandline instead of to the logfile.


Creating your own client (method 2)
-----------------------------------

Perhaps the above is all way too difficult. Perhaps you require special
services that are only available to your development team internally. Or
perhaps you have something similar already with which you want to
interface. In that case you could opt to write and run your own client
instead.

The API at www.officeshots.org is a simple XML-RPC API [3] that runs
over an HTTPS connection. You need an SSL client certificate though, but
it's all very basic and simple. The factory manual also has a chapter
devoted to building your own client [4].

[3] http://dev.officeshots.org/xmlrpc
[4] http://docs.officeshots.org/factory-guide/factory.html#id281838

The advantage is that you can use all the special one-off code, services
and APIs that you want because you never need to release your client and
it doesn't need to run on any other platforms. The downside is that you
would need to keep the client running. If it doesn't run, people cannot
use your applicaton in Officeshots.

-------------------

If all goes well then the factory will connect to Officeshots and see if
there are any jobs. This is called "polling". You should get a message
like "No jobs found. Sleeping".

After your first succesfull poll you should see your applications on
the front page of Officeshots. The front page is designed to only show
applications that did a succesfull poll in the last 5 minutes.

Now that the application is listed you can upload a document, check the
boxes for your applications and test if your factory correctly
downloads and converts them. If everything goes well you should see the
converted documents appear on the website.

Contact
-------

If you run into any problems, have questions or need support, feel free
to contact our project leader Sander Marechal [3]. For general problems
and ideas we suggest posting to plugtest at opendocsociety.org or using the
dedicated officeshots mailinglist [4] so that other people can read
and help as well. You need to register for the mailinglist before you
can post messages there.

[3] By mail: s.marechal at jejijk.com. By phone: + 31 85 877 5626
    (GMT+2, during business hours please). 
[4] http://lists.opendocsociety.org/mailman/listinfo/officeshots

Officeshots.org is available under Affero GPLv3, you are invited to
contribute features and code as well. Thank you for supporting
Officeshots.