General
What is Docmosis?
Who is it for?
Why use it?
How do I use it?
Is it fast?
Is it easy to use?
Is there any magic?
How does Docmosis compare to other products?
Templates
How do I create a template?
What features do the templates have?
What format(s) can my templates be in?
What format(s) can I produce?
Technical
How does it work?
Is it configurable?
Is it scalable?
How to I install it?
What versions of Java can be used?
What versions of OpenOffice can be used?
Pricing & Redistribution
What does it cost?
Can I re-distribute Docmosis in my own product?
Is it Open Source?
Can I upgrade from the Free Version to the Enterprise Version?
TroubleShooting
My document doesn't look like I expect. What has happend?
Why do I get the following error: "java.lang.UnsatisfiedLinkError: createJNI" ?
My Docmosis Converter won't start?
On linux memory appears to be leaking
I'm getting a license issue "no valid license available: your docmosis license has expired"
Known Issues
Help and Support
I'm stuck. What can I do?
General
What is Docmosis?
Docmosis is a system you can use to produce Word, PDF and Open Document Format (ODF) documents from within Java. The process starts with a Word or ODF document as a template, merges it with the provided data, and finally renders it into the final forms. The objective is to greatly improve the way systems produce documents.
Who is it for?
Docmosis is for companies and organisations that produce documents. The current releases target organisations which have access to their own development team(s) to integrate Docmosis with their existing systems. Docmosis is being used by customers in a broad set of areas including Defence, Health and Education.
Why use it?
There are several reasons to use Docmosis:
- Buliding Documents is much simpler
- Appearance (fonts, colours, layout etc) are determined by the template which is a simple Word or ODF document
- Developers can focus on obtaining the data and controlling the process not formatting
- Choice of output formats (Word, PDF, ODF, HTML, RTF, TXT)
- Ease of integration with existing systems
- Speed and scalability
How do I use it?
- Integrate Docmosis
- Java developers add the library to their application(s)
- Set up the configuration
- Optionally install components onto other hosts to distribute processing load
- Create templates using Word or Open Office
- Make calls to the Java API to populate the desired templates with the given data and return the result in the desired format(s)
Is it fast?
We think so. Every document production system promotes it's speed, however document rendering has always been an intensive process. Docmosis has addressed the issue by:
- Allowing the intensive processing components to be moved to other hosts
- Streamlined the population phase by pre-analyzing the template and converting it into an optimized population stream
The result is that on a typical desktop PC, documents are typically produced in a few hundred milliseconds (usually sub-second). This coupled with the ability to move the processing to as many other hosts as desired means that documents can be produced at impressive rates. The online demo shows the Docmosis performance on a specified machine spec.
Is it easy to use?
For developers, Docmosis is a Java API that is reasonably simple and the developers only need to deal with a few key classes. The developers need to:
- Collect the required data from their information sources
- Control the choice of template, output format and destination of the results
- Ask the Docmosis engine to render the documents
For the template authors/maintainers, Docmosis keeps things simple first. General experience with Word or OpenOffice Writer is all that is required and the ability to insert form fields or merge fields. Nothing more.
There are no complex macros or directives in the templates, yet the templates can still produce surprisingly sophisticated documents.
Setup and configuration are straight forward. The developers efforts will be focussed on getting the data out of the information systems required.
Is there any magic?
There most certainly is. Docmosis relies on the brilliance of Java and Open Office to achieve it's results. Java is required to run Docmosis and Open Office must be installed wherever the distributable converters are run. Open Office and Java support the Docmosis system and never require any user interaction.
What Docmosis does it does consistently, reliably and fast. New features will be added with coming releases and known issues are kept up to date on this site in the support page.
How does Docmosis compare to other products?
| Feature | Docmosis | Jasper/iReport | XML Publisher |
|---|---|---|---|
| Standard Editor for Templates |  |
 |
|
| True Doc format output | |
|
|
| Easy To Integrate | |
|
|
| Free/Low-Cost | |
|
|
Templates
How do I create a template?
A template is just a normal document which you can create, edit and update using either Word or Open Office Writer. Each time a template is modified, it must be "stored" by Docmosis to ready it for processing. If you have no form fields or merge fields in the document then it is a static template. Inserting merge fields, form fields and image placeholders into the template means the document will be populated with dynamic content when processed.
What features do the templates have?
The currently supported features are:
- Field insertion pretty much anywhere (header, body, footer, tables)
- Image insertion
- Table of contents and index page refreshing
- Repeating segments
- Conditional segments
- By-example table row grouping
- Repeating lists (bullets and numbered lists)
- Table cell background colouring
- Font manipulation (adding bold, italics etc)
The conditional and repeating segments can "nest" content to arbitrary levels. This means it is easy to have template logic which says something like, "if I have any hotel information, then show me all the floors for all the hotels I have in tabular form".
What format(s) can my templates be in?
- Word
- Open Document Format (ODF) documents as created by Open Office
What format(s) can I produce?
- Word
- Open Document Format (ODF) documents as created by Open Office
- RTF
- HTML
- TXT
Technical
How does it work?
The Docmosis engine uses custom technolgy to analyze and populate the template. It uses Open Office to perform conversion of the document from one format to the other. Pre-processing the template and the ability to distribute the processing effort provide impressive performance.
Is it configurable?
Yes, although configuration has intentionally been kept fairly simple. You only need to define where you would like the template store to reside and how the converters are distributed around different machines if you choose to do so. There are many other configurable parameters that can be overridden, but most of the time the defaults are expected to suffice.
Is it scalable?
Yes it is. The "converter" component which is the most processing intensive component can be optionally moved to a variety of hosts. Any host can run any number of converters and the host running the main Docmosis engine doesn't need to have any. This allows an arbitrary number of documents to be converted in parallel which is pretty impressive.
How to I install it?
The installation is fairly straight forward in all cases. Please refer to the documentation and release notes.
What versions of Java can be used?
Any version of Java from 1.4 onwards.
What versions of OpenOffice can be used?
OpenOffice versions 2.3, 2.4 and 3.0 are supported.
Note that if using OpenOffice 2.4 on a Linux/Unix system you may need to set an additional Docmosis parameter to reduce memory leakage. See On linux memory appears to be leaking for further details.
Pricing & Redistribution
What does it cost?
Docmosis comes in two forms:
- The Free version - fully featured but speed and scalability limited
- The Paid version - fully featured and unlimited scalability. Pricing is a one off purchase per server (or if virutal servers are being used, per virtual server). Special pricing applies if you have many servers or wish to redistribute Docmosis with your own system.
See the Pricing page for more details.
Can I re-distribute Docmosis in my own product?
You may re-distribute Docmosis with your own product provided you do not violate the license that comes with Docmosis. For the free version of Docmosis, this means you agree to acknowledge Docmosis as part of your product, and you and your customers will not decompile the software. Further it is only the free version of Docmosis that can be re-distributed without purchasing suitable Docmosis licenses.
Is it Open Source?
No. The source is not currently public in any form.
Can I upgrade from the Free Version to the Enterprise Version?
Yes this is trivial. Your existing installation only requires a new key and any new Converters you wish to deploy.
TroubleShooting
My document doesn't look like I expect. What has happend?
You should consistently get the same result from the document production. If you are not seeing something you expect or something is not populating, double check the field names you are using. You should also be aware of the known issues. Finally developers may use the tools available to them (such as the DebugDataProvider class) to help understand and debug the population process. More information is available in the documentation area.
Why do I get the following error: "java.lang.UnsatisfiedLinkError: createJNI"?
There are several known causes of this:
- incorrectly set LD_LIBRARY_PATH variable in Linux/Unix environments. See the runConverter.sh script in the download bundles to see how to set the LD_LIBRARY_PATH variable. Note this is not required in Docmosis versions from 1.2.0 onwards
- On 64-bit Linux systems a 32 bit install of Java must be present. OpenOffice (which is a key component of the Docmosis Converter) must be able to locate a 32 bit java install. Running javaldx (under the openoffice install area) should report at least one path to Java.
- If you are using OpenOffice 2.3 on a linux platform, you may need to have the open office "headless" package installed. This is particularly likely if you see the error "X11 error: Can't open display".
- Sites have occasionally reported that re-installing openoffice (even as late as version 3.0) has corrected the problem. The root cause has not been established or why the install did not work correctly the first time through.
My Docmosis Converter won't start?
As of Docmosis 2.2, the reason for startup failure and suggestions should be provided in the output
This is almost always due to an error when the converter attempts to launch OpenOffice. There are five known causes of this:
- incorrectly set LD_LIBRARY_PATH variable in Linux/Unix environments. See the runConverter.sh script in the download bundles to see how to set the LD_LIBRARY_PATH variable. Note this is not required in Docmosis versions from 1.2.0 onwards.
- On 64-bit Linux systems a 32 bit install of Java must be present. OpenOffice (which is a key component of the Docmosis Converter) must be able to locate a 32 bit java install.
- If you are using OpenOffice 2.3 on a linux platform, you may need to have the open office "headless" package installed. This is particularly likely if you see the error "X11 error: Can't open display".
- If you are using OpenOffice 3.0 on Ubuntu with no X11 or client GUI, you may need to install another version of Java. The JDK that comes with some versions of Ubuntu can disagree with OpenOffice 3.0.
- Sites have occasionally reported that re-installing openoffice (even as late as version 3.0) has corrected the problem. The root cause has not been established or why the install did not work correctly the first time through.
On linux memory appears to be leaking
The final version of Docmosis 1.1 and all newer versions manage OpenOffice carefully, and so memory leaking should not occur.
If you are using and old version of Docmosis and OpenOffice 2.4 under linux for your Converters, then it may be that the "headless" mode is causing the leak. This can be circumvented by setting the following Docmosis property
docmosis.converter.launch.args=-minimized -invisible
in your docmosis.properties file (or System property).
no valid license available: your docmosis license has expired
You have downloaded Docmosis, but forgot to get the free key. Go to the downloads page to get your free community key. You will need to plug the key into your docmosis.properties file.
Known Issues
Known Issues for v1.1 - v2.0
| Output Format | Feature | Issue | Workaround |
|---|---|---|---|
| Any | MSWord | text frames crash Word97 or Word2000 if double clicked or properties shown | Avoid text frames or don't use MSWord97/2000 for editing produced documents |
| Any | Any | Problems occur launching a converter on 64-bit Linux | see Converters on 64-bit linux in the FAQ |
| Any | Any | Problems occur launching a converter on Ubuntu Headless with OpenOffice 3.0 | Issues with being unable to start a converter on Ubuntu Headless can often be resolved by using a different JDK than the default one installed with Ubuntu. Try another JDK. |
| Any | MSWord | Fields are not populating and are actually making it to the final document looking something like <<fieldName>>. | The field you are using has something wrong with it in your template. This could be a field-within-field type of problem or some form of styling issue. Delete and re-create the field. |
| Any | MSWord 2003+ | Table Cell background colours are lost. This is a bug in OpenOffice 3.1.0 and 3.1.1 | Don't use OpenOffice 3.1.0 (earlier versions don't have this issue) |
| Any | Any | Tables and fields can go missing | Don't use OpenOffice 3.0.1 |
Help and Support
I'm stuck. What can I do?
Check our documentation and support areas. If the answer is not there, contact us.