Using the doc converter API

October 8, 2024

Jahia exposes the document transformation API also through servlet API (apart from the Java API). The org.jahia.bin.DocumentConverter controller is responsible for communication with the conversion service.

Uploading and converting documents

The following code shows how the conversion API can be used in templates to upload and convert documents.

Uploaded document gets converted to the selected format and written back into the response by the DocumentConverter servlet:

<form id="conversion" action="${pageContext.request.contextPath}/cms/convert"
  enctype="multipart/form-data" method="post">
<p>
        <label for="file">Choose a file to upload:&nbsp;</label>
        <input name="file" id="file" type="file" />
</p>
<p>
<label for="mimeType">Target document type:&nbsp;</label>
<select id="mimeType" name="mimeType">
    <option value="application/pdf">Adobe PDF</option>
    <option value="application/msword">Microsoft Word Document</option>
    <option value="application/vnd.ms-excel">Microsoft Excel Sheet</option>
    <option value="application/vnd.ms-powerpoint">Microsoft Powerpoint Presentation</option>
    <option value="application/vnd.oasis.opendocument.text">OpenDocument Text</option>
    <option value="application/vnd.oasis.opendocument.spreadsheet">OpenDocument Spreadsheet</option>
    <option value="application/vnd.oasis.opendocument.presentation">OpenDocument Presentation</option>
    <option value="application/x-shockwave-flash">Flash</option>
</select>
</p>
<p><input type="submit" value="Convert file" /></p>
</form>

The example is taken from the tools/docConverter.jsp.

Converting documents from repository

Any document in the repository can be converted into another format using the same DocumentConverter servlet by using the URL of the following format:

http://<host>:<port>/cms/convert/<workspace>/<file-node-path>.<target-format-extension> 

For example to get a PDF version of a Microsoft Office Word file, located in the repository's default workspace (edit) under /shared/files/Report.doc, the following URL can be used:

http://localhost:8080/cms/convert/default/shared/files/Report.doc.pdf 

And for generating a link to the PDF version of a file node one can use the code:

<a href="${url.convert}${fileNode.path}.pdf">${fileNode.name} as PDF</a> 

Using Document-Converter component

Jahia provides a built-in UI component for rendering a document conversion form, which allows users to upload documents into their home folder, performing different type conversions on the fly.

The component is available in the edit mode selector (left-side panel) in the Editorial content group:

The form with a table of converted document is rendered as shown below:

Conversions in business rules

It is also possible to use document conversion service directly from business rules to e.g. perform automatic conversions when a document is uploaded or updated. An example of a rule the /templates/docConverter/rules.drl file, which automatically creates a PDF version of the uploaded/modified document is given below:

rule "Auto-convert to PDF"
  when
    A file content has been modified
      - the mimetype is not application/pdf
    then
      Convert node to type "application/pdf"
end