FAQ's

If you can't find what you are looking for in our FAQ, please ask us the question directly.

General

What is Docmosis?

Docmosis can be used by any software application to generate documents and reports in Micrsoft Word(Doc/DocX), PDF, Open Document Format (ODT) and other document formats.

The process starts by building a Microsoft Word or OpenOffice document as a template.  Your application sends data to Docmosis which Docmosis merges with the template to produce the finished document.

The Docmosis-Java product allows you to integrate this capability into a Java application.

The Docmosis Cloud service has a simple REST API and makes Docmosis available to any internet connected application.

Tornado is a stand alone document generation engine that provides access to Docmosis capabilities as a Web Service via a REST API.

Why use it?

Put simply: Increasing productivity.

Docmosis makes creating documents and reports faster and easier, because:

  • Docmosis Templates can be created using the well known tools Mircosoft Word or OpenOffice/LibreOffice.  This allows non-developers to be able to contribute to the document design and layout process.
  • Placeholdes can be added just by typing (eg: <<fristName>>) without having to learn how to use extra plug-ins.  The Docmosis syntax is easy to learn and understand.
  • Docmosis integrates easily with most software applications.
  • Docmosis has been engineered to work at Enterprise scale with considerations for memory usage and processing load.

Anyone that has built documents and reports knows that it's the tricky edge cases that really test the limits of a tool.  With Docmosis you will be pleasantly surprised at the thought that has gone in to handling those cases.

We pride ourselves on offering comprehensive and detailed Support.  Feel free to test our Support team while trialing Docmosis.

 

Who is it for?

Docmosis is for companies or organisations that are looking for ways to improve the speed and efficency with which documents and reports are created.   They will probably have access to their own software development team(s) to integrate Docmosis with their existing software systems.

Docmosis significantly improves the collaboration between Software Developers and non-Developers (like End Users / Business Analysts) by allowing the authoring and design of documents to be done using well known software packages like: Microsoft Word or OpenOffice/LibreOffice.

Docmosis is being used by customers in a broad set of areas including Legal, Medical, Defence, Logistics, Finance, Health and Education.

Is it fast?

We think so. Every document production system promotes it's speed, however document rendering has always been a resource intensive process. Docmosis has addressed the issue by:

  1. Allowing the intensive processing components to be moved to other servers
  2. 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.

How do I use it?

Docmosis needs to be integrated in to your software application by a Software Developer.

Java applications can embed the Docmosis-Java product by adding the docmosis.jar to their application.

Tornado can be used by an application developed in any language.  Tornado is a stand alone document generation engine that provides access to Docmosis capabilities as a Web Service via a REST API.

The Docmosis Cloud service has a simple REST API and makes Docmosis available to any internet connected application.

Templates

What format(s) can my templates be in?

  • Microsoft Word (DOC / DOCX)
  • Open Document Format (ODT) documents as created by OpenOffice or LibreOffice

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
  • Table row repeating which supports nested tables and nested repeating rows
  • Repeating lists (bullets and numbered lists)
  • Table cell background colouring
  • Table row/column removal
  • Font manipulation (adding bold, italics etc)
  • Template Merging - templates can be included in other templates 
  • ...and more...

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 I produce?

  • Word
  • Open Document Format (ODT) documents as created by Open Office
  • PDF
  • RTF
  • HTML
  • TXT
  • DocX

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.

How to I install it?

The installation is fairly straight forward in all cases. Please refer to the developer documentation.

What versions of Java can be used?

Any version of Java from 1.4 onwards.

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.

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.

Pricing & Redistribution

Is it Open Source?

No. The source is not currently public in any form.

What does it cost?

Docmosis comes in three forms:

  1. Docmosis-Java - embed Docmosis in to your Java application.
  2. Tornado - use Docmosis as a Web Service running on your servers.
  3. Cloud - use Docmosis as a Cloud based Web Service.  Monthly fees apply

See the Buy pages for more details.

 

Can I re-distribute Docmosis in my own product?

Please contact us if you would like to know about re-distribution options and pricing.

Can I upgrade my license?

Yes this is a simple process. If you run Docmosis on your own site, you install your new license key and restart the application(s). If you are using our cloud service, your plan can be modified with no software or configuration changes required on your part.

Troubleshooting

No valid license available: your docmosis license has expired

You need a valid License Key to run Docmosis.

 

If you have not previously requested a Licence Key...

You can do so here: Docmosis-Java / Tornado.

You will need to add the License key into your docmosis.properties file.

Please check that you have correctly cut/paste all of the lines from the Licence Key email we sent you.

 

If you are setting up Docmosis for the first time...

Occasionally different email clients add extra carriage returns into the Licence Key we send you.

Please contact Support and we can send you a .txt file with the licence key.

 

If you have preivously used Docmosis...

Then your Licence Key has expired.

Please contact Support for an extension.

 

Converter gives "creation of executable memory area failed" on startup on linux

The script launching the converter does not have the HOME environment variable set to a writable location. This typically happens with wrapper programs or locked down accounts and doesn't appear to affect Docmosis. Set the HOME environment variable to correct the issue.

32 Bit vs 64 Bit environments.

Please feel free to contact Support for help with setting up your environment.

Docmosis can run in 32 Bit or 64 Bit environments.

However, you must make sure that the components used are matching or at least compatible.

 

OpenOffice / LibreOffice

The Java version (32/64 Bit) being used to run Docmosis must match the version (32/64 Bit) of OpenOffice / LibreOffice that you install.

    You may find that the only option for your operating system is a 32 Bit build of OpenOffice / LibreOffice.  In this case you must use a 32 Bit (or 32 Bit compatible) version of Java to run Tornado or the Docmosis converters.

    Some 64 bit Java versions allow you to specify a "-d32" flag to run in 32 Bit mode.

    Please keep in mind that you can run Tornado or the Docmosis converters separately from your application.  They can be 32 Bit and run using a different JVM to your main applicaiton (which could be 32 Bit or 64 Bit).

     

    ODFConverter

    This is an optional component for producing DocX and it is only available in a 32 Bit build (at the time of writing).  This can be installed and run on 64 Bit Linux platforms as long as the 32 Bit Linux libraries are installed (see below).

    For Example: to allow 32 Bit OdfConverter to run on 64 Bit CentOS 6.4, the libraries can be installed with the following commands to allow OdfConverter to run:

    1. sudo yum install compat-libstdc++-296.i686
    2. sudo yum install compat-libstdc++-33
    3. sudo yum install libstdc++.i386
    4. sudo yum install compat-libstdc++-33
    5. sudo yum install glib2-2.22.5-7.el6.i686
    6. sudo yum install fontconfig-2.8.0-3.el6.i686
    7. sudo yum install libXrender-0.9.7-2.el6.i686
    8. sudo yum install zlib-1.2.3-29.el6.i686
    9. sudo yum install libjpeg-turbo-1.2.1-1.el6.i686
    10. sudo yum install libpng-1.2.49-1.el6_2.i686

     

    Trouble with JBOSS and Embedded Converters - "Unable to instantiate class"

    If you are using JBOSS (5 onwards) and Docmosis embedded Converters, you may have trouble starting Docmosis with errors like:

    Unable to instantiate class:com.docmosis.converter.openoffice.LocalOpenOfficeConverter:com/sun/star/connection/NoConnectException

    In the Logs you should see the suggestion:

    consider setting "docmosis.openoffice.useCustomLoader=true" 

    If that doesn't help then please try setting:

    docmosis.openoffice.useCustomLoader=false
    docmosis.openoffice.libraries.loadIntoSystemCL=true

     

    Please feel free to contact Support for help with setting up your environment.

     

    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 an 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).

    Images not appearing in RTF documents

    If you are not seeing images when generating RTF documents try using different format images (eg JPEG). For example, OpenOffice (confirmed up to version 3.3.0) can produce RTF documents where PNG images cannot be seen.

    Why do I get the following error: "java.lang.UnsatisfiedLinkError: createJNI"?

    There are several known causes of this:

    1. 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
    2. 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.
    3. 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".
    4. 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.

    Known Issues

    Known Issues for v1.1 - v2.0

    Output FormatFeatureIssueWorkaround
    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 "My Docmosis Converter won't start" above
    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
    Any MS Word / DOC Images lose transparency Switch to LibreOffice or don't rely on transparency in images

    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:

    1. 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.
    2. 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.
    3. 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".
    4. 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.
    5. 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.

    Using LibreOffice 4 on AWS EC2 image Amazon Linux

     

    If you are running Docmosis Converters with:

     AWS Linux

     Libre Office 4.2

    and you encouter the following errors:

      error while loading shared libraries: libXinerama.so.1

     error while loading shared libraries: libcups.so.2

     error while loading shared libraries: libdbus-glib-1.so.2

    you will need to run the following command to install the required libraries:

      sudo yum install libXinerama.x86_64 cups-libs dbus-glib


    Libre Office 4,2 will then have the libraries it requires to run and the Docmosis Converter should launch succesfully.

     

     

    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. 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 support area.

    Configuring Docmosis V3 to work with Libre Office 5

    If you are trying to run an older version of Docmosis (eg v3) with a newer version of Libre Office (eg v5), then a simple configuration change is required.

    Add the following lines to your settings (usually in your docmosis.properties file):

     searchpath=[home]/program/classes;[home]/Basis/program/classes;[home]/URE/java;[home]/basis-link/program/classes;[home]/basis-link/ure-link/share/java;[home]/ure-link/share/java;[home]/ure/share/java;[home]/Resources/java

     docmosis.openoffice.libraries.searchpath=[home]/basis-link/ure-link/lib;[home]/ure-link/lib;[home]/ure/bin;[home]/program;[home]/Frameworks

     docmosis.openoffice.libraries.list=uwinapi;sal3;libuno_sal.so.3;libuno_sal.dylib.3;jpipx;jpipe;libjpipe.jnilib

    The Docmosis converter should then start happily.

    Libre Office 5 missing shared library libGL.so.1

    If you hit an error like the following during Docmosis startup:

      error while loading shared libraries: libGL.so.1: cannot open shared object file

    then you can likely solve it using:

      sudo yum install cairo

     

    Help & Support

    I'm stuck. What can I do?

    You will find extensive documentation in our Resources section.

    If the answer is not there please feel free to Contact Support.