Tornado
self-hosted document generation software
Add document generation to applications built with Java, .NET, PHP, Ruby and more.
- Tornado provides the Docmosis engine as a web service that is easy to integrate with most modern platforms.
- Perfect for teams that already manage their own servers and prefer to host their own software.
The service has been designed to efficiently perform transactional requests, generating single-page documents sub-second, or to meet large batch processing requirements and is capable of generating hundreds-of-thousands of documents-per-hour.
Explore the diagrams on the right to understand key Tornado concepts and hosting/scaling the installation.
# Use the local Tornado service running on your serversurl = URI(“http://localhost:8080/api/render”)
http = Net::HTTP.new(url.host, url.port)# Specify data, template file and output file/format
DATA = ‘{“message”:”This Docmosis engine is working great!”}’;
TEMPLATE_NAME = ‘myTemplate.docx’;
OUTPUT_NAME = ‘result.pdf’;# Create the POST request
request = Net::HTTP::Post.new(url)
request[“Content-Type”] = ‘application/json’
request.body = “{” +
“\”templateName\”: \”#{TEMPLATE_NAME}\”,” +
“\”outputName\”: \”#{OUTPUT_NAME}\”,” +
“\”data\”:#{DATA}}”# Call Tornado with the request and save the response
response = http.request(request)
File.open(OUTPUT_NAME,”wb”){|f|f.write(response.body)}
An API-First Approach
Designed with developers in mind.
As a self-hosted document generation engine, Tornado listens and responds to commands sent to the API. A typical document workflow is as follows:
- The application sends a render request by performing a HTTPS POST.
- The payload contains: the data; the template name; the required output format(s).
- Tornado merges the data with the template.
- Generated documents are typically returned to the calling application, allowing the application to perform further actions with the files.
The API offers convenient features such as Dev Mode. In the event of an error, this mode controls whether:
- A document IS generated, with the errors highlighted in the document (helpful during development); or,
- A document IS NOT generated. Instead an error code and message are returned to the calling application (perfect for production).
The Tornado and Cloud APIs use similar endpoints and parameters for rendering documents. For initial evaluation, consider starting with Cloud. After initial proof-of-concept work, download and run the self-hosted Tornado engine, then easily switch by changing the API URLs.
Getting Started
Download, install and run the Tornado software
Start a free trial to receive a Tornado license key valid for 30 days. The trial key can be used to run a single converter (T-100 equivalent) with options to trial higher powered editions or extend the trial on request.
- Experiment with rendering documents via the Tornado web portal
- Progress to the Code Samples to understand key API concepts
- Call the Tornado API from your application to generate documents
Follow the instructions on our Resources Website to help you get started.
Security Statement
Understand how to configure and protect your Tornado installation to ensure privacy of your applications data.
1. Tornado is a software application that you are responsible for downloading, installing, configuring and running.
2. Tornado is primarily used by other software applications via the API.
3. Tornado provides a web-based interface for initial configuration and functionality assessment during the trial and proof-of-concept phases. Most production Tornado installations will apply the required configuration (license keys, working folder, etc.) as startup parameters or as values derived from the registry/file system.
4. It is expected that Tornado will be run in a protected environment where network access is restricted (both inbound and outbound). In this context, concerns regarding access and vulnerabilities are under your complete control.
5. Tornado does not attempt to “reach out” to Docmosis to validate the license key or report statistics. Docmosis staff have no access or visibility to any Tornado installation or your servers/environments/data where Tornado is deployed.
6. Stability is a key feature of Tornado, as document generation must be robust, consistent and always available. New releases of the software are not pushed automatically. You have the option to obtain and install any software updates manually.
7. Software updates could potentially affect the layout and formatting of generated documents and should always be followed by testing of the templates and the generated documents.
8. Docmosis templates (as distinct from generated documents or data) reside in a persistent cache. As a general rule templates should not contain private data.
9. While a render request is being executed, the data and generated documents exist in a temporary working directory until delivery completes or an error occurs, at which point they are immediately and automatically deleted.
Hosting Tornado
Tornado is a stand-alone application.
Once running, Tornado waits for jobs.
The driving application sends a document generation job, called a render request, to the Tornado API.
Requests are performed synchronously. The calling thread in the main application will block while the request is serviced and the generated file is returned.
Converters and Queuing
A single Tornado installation can start and manage multiple converters.
Converters are the workhorse of Tornado. Running multiple converters makes it possible to service multiple requests in parallel.
Tornado maintains an internal queue of pending jobs and ensures efficient use of the available converters.
Initial Trial Setup
During the trial, or for development, it is common to run the main application and Tornado on the same server.
Using the trial license key, Tornado will start a single converter.
The templates reside in a folder, on the same server, that is specified during the initial configuration.
In Production
Tornado can be hosted on its own server with requests sent over the local network.
This enables processing load, and dependencies, to be moved away from the main application server.
Tornado can be configured to run at server startup, with the required configuration (license keys, working folder, etc.) as startup parameters or derived from the registry/file system.
Template Storage
Tornado can be configured to source templates from external sources.
Templates can reside in public cloud storage, such as AWS S3 or Azure Blob storage.
This allows multiple instances of Tornado to share a single source of templates.
The application can upload/manage the templates via the API of those storage services.
Sharing Tornado
One application, distributed over multiple servers, can share a single Tornado installation, over the network.
It is expected that Tornado will run in a protected environment where network access is restricted (both inbound and outbound) to the calling applications.
The number of converters can be fine tuned to match the specifications of the server hosting Tornado.
Scaling and Redundancy
Multiple Tornado installations with a shared template repository.
Tornado can be hosted on Linux or Windows, or using a containerized approach such as Docker, and is well suited to running on public cloud services such as AWS or Azure.