Conversion API

Collabora Online allows you to convert between various file formats easily. To do so, all you need to do is to HTTP POST the content of the file to the specific endpoint and send optional parameters to change the defaults of the conversion process.

API: HTTP POST to /cool/convert-to/<format>

Important

The convert-to endpoint is restricted to allowed host addresses that can be set in the coolwsd.xml configuration file. The IP addresses have to be added as dot-escaped net.post_allow.host entries.

Note

Alternatively you can omit the <format>, and instead provide it as another parameter (format=<format>).

Supported Input Formats

Document Type

Input Formats

Writer

sxw, odt, fodt, stw, ott, doc, dot, docx, docm, dotx, dotm, wpd, pdb, hwp, wps, wri, lrf, mw, rtf, txt, fb2, cwk, pages, abw, 602, sxg, odm, otm, oth

Calc

sxc, ods, fods, stc, ots, xls, xla, xltx, xltm, xlsx, xlsb, xlsm, dif, slk, csv, tsv, dbf, wk1, wks, xlr, 123, qpw, wb1, wq1, wq2, gnumeric, numbers

Impress

sxi, odp, fodp, sti, otp, ppt, pot, pptx, pptm, potx, potm, ppsx, cgm, key

Draw

sxd, odg, fodg, std, otg, svg, dxf, emf, wmf, cdr, vsd, vsdx, vss, pub, p65, wpg, fh, bmp, png, gif, tiff, jpg, jpeg, pdf

Supported Output Formats

Document Type

Output Formats

Writer

doc, docm, docx, fodt, html, odt, ott, pdf, rtf, txt, xhtml, png

Calc

csv, fods, html, ods, ots, pdf, xhtml, xls, xlsm, xlsx, png

Impress

fodp, html, odg, odp, otp, pdf, potm, pot, pptm, pptx, pps, ppt, svg, swf, xhtml, png

Draw

fodg, html, odg, pdf, svg, swf, xhtml, png

Note

Of course not every input/output combination makes sense or works at all. Be reasonable. See a few examples below.

Optional Parameters

lang – Language (locale)

The lang parameter parameter sets the language or locale. By default it is English (USA). When the document contains formatted date fields or ther locale-dependent content, the desired display/output format can be guaranteed by passing this parameter. The value should be a BCP47 language tag, for example lang=fr-FR.

options – Export Filter Options

With the options parameter it is possible to pass a large variety of export filter options. The supported value strings depend on the output format. In some cases the value is a JSON, that allows to pass a complicated option set to the filter in a maintainable manner.

PDF Filter Options

In the interactive PDF export options dialog there are many options, and it is also possible to set any of them in the JSON payload of the options parameter. There are also a few options, that are not available on the graphical user interface, but can be set via this API.

For example to set the range of the exported pages to export from page 2 to the end of the document, the following JSON should be sent:

{
    "PageRange": {
        "type": "string",
        "value": "2-"
    }
}
Options from the General tab of PDF Export dialog

For more information please refer to Collabora Office Help – Export as PDF – General tab.

Name

Type

Example value

Description

PageRange

string

1,3,5-6

Export page range

UseLosslessCompression

boolean

true

Lossless compression of images

Quality

long

90

JPEG compression quality in %

ReduceImageResolution

boolean

true

Whether to reduce image resolution

MaxImageResolution

long

75

When ReduceImageResolution is true, this sets the maximal image resolution in DPI. Accepted values are: 75, 150, 300, 600, 1200. The default is 300.

Watermark

string

e.g. DRAFT, CONFIDENTIAL etc.

Draws a transparent watermark accross each page

WatermarkColor

long

255

The red (R), green (G), blue (B) and transparency (T) values can be 0-255. The value is calculated as T<<24+R<<16+G<<8+B.

WatermarkFontName

string

Helvetica

The name of the font to be used

WatermarkFontHeight

long

80

Font size of watermark text (in points?). By default the text is resized to fit the best.

WatermarkRotateAngle

long

450

The rotation angle of watermark text in 1/10th of degree

TiledWatermark

string

e.g. DRAFT, CONFIDENTIAL etc.

This type of watermark is drawn accross “tiles” of a document. A tile is e.g. 256×256 px area. Color, font, and rotation cannot be set via API.

SelectPdfVersion

long

20

By default the output is PDF 1.7, but other versions of the PDF standard can be forced. The possible values are 1, 2, 3, 4, 15, 16, 17, 20 for PFD/A1-b, PDF/A2-b, PDF/A3-b, PDF/4b, PDF 1.5, PDF 1.6, PDF 1.7 and PDF 2.0 respectively.

PDFUACompliance

boolean

true

Universal Accessibility (PDF/UA)

IsAddStream

boolean

true

Hybrid PDF (embed ODF file)

ExportFormFields

boolean

true

Create PDF form

FormsType

string

FDF

Submit format: FDF, PDF, HTML or XML

AllowDuplicateFieldNames

boolean

true

Allow duplicate field names

UseTaggedPDF

boolean

true

Tagged PDF (add document structure)

ExportBookmarks

boolean

true

Export outlines

ExportNotes

boolean

true

Comments as PDF annotations

ExportNotesInMargin

boolean

true

Comments in margin

ExportNotesPages

boolean

true

Export notes pages (Impress)

ExportOnlyNotesPages

boolean

true

Export only notes pages, not slides (Impress)

ExportHiddenSlides

boolean

true

Export hidden slides/pages (Impress/Draw)

IsSkipEmptyPages

boolean

false

Export automatically inserted empty pages (Writer) – true = don’t export, false = export

ExportPlaceholders

boolean

true

Export placeholders (Writer)

SinglePageSheets

boolean

true

Whole sheet export

UseReferenceXObject

boolean

true

Use reference XObjects
Options from the Initial View tab of PDF Export dialog

For more information please refer to Collabora Office Help – Export as PDF – Initial View tab.

Name

Type

Example value

Description

InitialView

long

1

0 – Page only, 1 – Outline and page, 2 – Thumbnails and page

InitialPage

long

2

Set the page number of initial page.

Magnification

long

3

0 – Default zoom, 1 – Fit in window, 2 – Fit width, 3 – Fit visible, 4 – Custom zoom factor

Zoom

long

85

Zoom level a PDF document is opened with, when Magnification is set to 4.

PageLayout

long

2

0 – Default, 1 – Single page, 2 – Continuous, 3 – Continuous facing

FirstPageOnLeft

boolean

true

First page is left
Options from the User Interface tab of PDF Export dialog

For more information please refer to Collabora Office Help – Export as PDF – User Interface tab.

Name

Type

Example value

Description

ResizeWindowToInitialPage

boolean

true

Resize window to initial page

CenterWindow

boolean

true

Center window on screen

OpenInFullScreenMode

boolean

true

Open in full screen mode

DisplayPDFDocumentTitle

boolean

true

Display document title in window title of PDF viewer application

HideViewerMenubar

boolean

true

Hide menubar

HideViewerToolbar

boolean

true

Hide toolbar

HideViewerWindowControls

boolean

true

Hide window controls

OpenBookmarkLevels

long

2

Specifies how many bookmark levels should be opened in the reader application when the PDF gets opened. -1 means all levels.

UseTransitionEffects

boolean

true

Use transition effects (Impress)
Options from the Security tab of PDF Export dialog

For more information please refer to Collabora Office Help – Export as PDF – Security tab.

Name

Type

Example value

Description

EncryptFile

boolean

true

Whether to encrypt the PDF file. It has to be set together with DocumentOpenPassword.

DocumentOpenPassword

string

Password to open the PDF document

PermissionPassword

string

Password to change PDF permissions

Printing

long

1

Specifies what printing is allowed. 0 – Not permitted, 1 – Low resolution (150 dpi), 2 – High resolution

Changes

long

1

Specifies the change allowed to the document. 0 – Not permitted, 1 – Inserting, deleting, and rotating pages, 2 – Filling in form fields, 3 – Commenting, filling in form fields, 4 – Any, expect extracting pages

EnableCopyingOfContent

boolean

false

Enable copying of content

EnableTextAccessForAccessibilityTools

boolean

false

Enable text access for accessibility tools
Options for Digital Signatures

It is possible to digitally sign a PDF document via the conversion API, but it is a bit different than interactive document signing. (See Document signing.) The signing certificate and its key, and the CA certificate have to be passed as strings (PEM format) to the endpoint. The first four parameters are mandatory.

Name

Type

Example value

Description

SignPDF

boolean

true

Set this true when you want to digitally sign the exported PDF

SignCertificateCertPem

string

The signing certificate in PEM format

SignCertificateKeyPem

string

The key for the signing certificate in PEM format

SignCertificateCaPem

string

The CA certificate of the signing certificate in PEM format

SignatureLocation

string

Cambridge, UK

Optional location information about the digital signature, that will be embedded into the PDF

SignatureReason

string

I am approving this document

Optional reason why you digitally signed this PDF

SignatureContactInfo

string

John Doe <john.doe@example.com>

Optional contact information of the signer of the document

SignaturePassword

string

The password used for protecting the private key associated with the selected certificate

SignatureTSA

string

https://freetsa.org/tsr

URL of the Time Stamp Authority. If not given, the signature will not be timestamped, but will use the current time from the Collabora Online server.

CSV Filter Options

The CSV export filter options are described in detail on the Collabora Office Help – CSV Filter Options page. For example options=44,34,76 sets the field separator to ,, the text delimiter to ", and the character set to UTF-8.

infilterOptions – Import Filter Options

This parameter can be used to change the default behaviour of the CSV import filter. The description of the possible values is on the Collabora Office Help – CSV Filter Options page. For example infilterOptions=44,34,76,1 sets the field separator to ,, the text delimiter to ", the character set to UTF-8, and the reading will start from line 1.

Deprecated Parameters

Note

Parameters in this section are deprecated and may be removed from future versions of Collabora Online. All of their functionality can be implemented with the options parameter described above.

PDFVer – PDF Version

When the output format is PDF, this parameter sets the PDF version for the respective type of PDF to be used for the output file. Example: PDFVer=PDF/A-2b. (Obsoleted by SelectPdfVersion)

Supported values

PDF-1.5

PDF-1.6

PDF-1.7

PDF-2.0

PDF/A-1b

PDF/A-2b

PDF/A-3b

PDF/A-4

FullSheetPreview – Fit the entire worksheet on one page

This parameter can be used when the input document is a spreadsheet, and output format is PDF. Ignores the paper size, print ranges, and visibility settings of each worksheet, and places the full content of every worksheet (even hidden one) onto a single page scaled to fit. Example: FullSheetPreview=true. (Obsoleted by SinglePageSheets)

Examples

Important

The -k in the following curl examples disables certificate validation as it is unlikely you have one in that situation. On a production system, please make sure you have valid certificates and do not disable the validation with -k.

Here you convert a plain text file to OOXML format (docx).

curl -k -F "data=@test.txt" https://localhost:9980/cool/convert-to/docx > out.docx

or here is a HTML form, that takes a file to be converted to docx:

1<form action="https://localhost:9980/cool/convert-to/docx" enctype="multipart/form-data" method="post">
2 File: <input type="file" name="data"><br/>
3 <input type="submit" value="Convert to DOCX">
4</form>

Alternatively you can omit the <format>, and instead provide it as another parameter. In this example you convert an OpenDocument Text (odt) file to PDF.

curl -k -F "data=@test.odt" -F "format=pdf" https://localhost:9980/cool/convert-to > out.pdf

or here is a HTML form that takes a file and the output format:

1<form action="https://localhost:9980/cool/convert-to" enctype="multipart/form-data" method="post">
2 File: <input type="file" name="data"><br/>
3 Format: <input type="text" name="format"><br/>
4 <input type="submit" value="Convert">
5</form>

In the following, more complex PDF conversion example the page 1 and pages from 8 to 30 are extracted from a book, a red watermark is put accross the pages in 45° saying “DO NOT DISTRIBUTE”, and the output document can only be opened with a password “S3cret”.

{
    "PageRange": {
        "type": "string",
        "value": "1,8-30"
    },
    "Watermark": {
        "type": "string",
        "value": "DO NOT DISTRIBUTE"
    },
    "WatermarkColor": {
        "type": "long",
        "value": "16711680"
    },
    "WatermarkRotateAngle": {
        "type": "long",
        "value": "450"
    },
    "EncryptFile": {
        "type": "boolean",
        "value": "true"
    },
    "DocumentOpenPassword": {
        "type": "string",
        "value": "S3cret"
    }
}

curl -k -F "data=@Book.pdf" -F "format=pdf" -F "options={\"PageRange\":{\"type\":\"string\",\"value\":\"1,8-30\"},\"Watermark\":{\"type\":\"string\",\"value\":\"DO NOT DISTRIBUTE\"},\"WatermarkColor\":{\"type\":\"long\",\"value\":\"16711680\"},\"WatermarkRotateAngle\":{\"type\":\"long\",\"value\":\"450\"},\"EncryptFile\":{\"type\":\"boolean\",\"value\":\"true\"},\"DocumentOpenPassword\":{\"type\":\"string\",\"value\":\"S3cret\"}}" http://localhost:9980/cool/convert-to > out.pdf