libreoffice-online/wsd/reference.txt

LibreOffice Online API
=======================

Document conversion:
    - API: HTTP POST to /lool/convert-to/<format>
        - the format is e.g. "png", "pdf" or "txt"
        - the file itself in the payload
    - example
        - curl -F "data=@test.txt" https://localhost:9980/lool/convert-to/docx > out.docx
	- or in html:
          <form action="https://localhost:9980/lool/convert-to/docx" enctype="multipart/form-data" method="post">
              File: <input type="file" name="data"><br/>
              <input type="submit" value="Convert to DOCX">
          </form>

    - alternatively you can omit the <format>, and instead
      provide it as another parameter
    - example
        - curl -F "data=@test.odt" -F "format=pdf" https://localhost:9980/lool/convert-to > out.pdf
        - or in html:
          <form action="https://localhost:9980/lool/convert-to" enctype="multipart/form-data" method="post">
              File: <input type="file" name="data"><br/>
              Format: <input type="text" name="format"><br/>
              <input type="submit" value="Convert">
          </form>

WOPI Extensions
===============

LibreOffice Online uses WOPI protocol to interact with hosts who wants to
integrate LibreOffice Online in them.

Refer to WOPI docs[https://wopi.readthedocs.io/en/latest/] for detailed
information. This documentation only mentions extensions to upstream WOPI protocol,
WOPI extensions, that are implemented by LibreOffice Online backend in addition to
upstream WOPI protocol.

(Please note that upstream WOPI implementation is also not 100% complete)

CheckFileInfo response properties
----------------------------------

HidePrintOption
	If set to true, hides the print option from the filemenu bar in the UI

HideSaveOption
	If set to true, hides the save button from the toolbar and file menubar
	in the UI

HideExportOption
	Hides 'Download as' option in the file menubar

DisablePrint
	Disables print functionality in libreoffice online backend. If true,
	HidePrintOption is assumed to be true

DisableExport
	Disables export functionality in backend. If set to true,
	HideExportOption is assumed to be true

DisableCopy
	Disables copying from the document in libreoffice online
	backend. Pasting into the document would still be possible.
	However, it is still possible to do an "internal" cut/copy/paste.

DisableInactiveMessages
	Disables displaying of the explanation text on the overlay when the
	document becomes inactive or killed.  With this, the JS integration
	must provide the user with appropriate message when it gets
	Session_Closed or User_Idle postMessage's.

EnableOwnerTermination
	If set to true, it allows the document owner (the one with OwnerId =
	UserId) to send a 'closedocument' message (see protocol.txt)

UserExtraInfo
	JSON object that contains additional info about the user, namely the
	avatar image.

	Example: 'UserExtraInfo' => [ 'avatar' => 'http://url/to/user/avatar', 'mail' => 'user@server.com' ]

	Note: There is strict Content Security Policy that restricts image
	resources (img-src), therefore the avatar URL must not violate the
	CSP,  otherwise it will show as broken images.

WatermarkText
	If set to a non-empty string, is used for rendering a watermark-like
	text on each tile of the document

Note that it is possible to just hide print,save,export options while still
being able to access them from WOPI hosts using PostMessage API (see loleaflet/reference.html)

Alternative authentication possibility
--------------------------------------

Instead of the 'access_token', it is possible to pass an 'access_header' at
the places where the 'access_token' would be used in the initial iframe setup.

The 'access_header' can be eg. of a form

    Authorization: Basic abcd1234==

This header is then used in all the WOPI calls like PutFile, GetFile or
CheckFileInfo, allowing Basic authentication to work.

PutFile headers
---------------

PutFile additionally indicates whether the user has modified the document
before the save, or if they just pressed the Save button without any
modification.  The following header:

    X-LOOL-WOPI-IsModifiedByUser

will have the value 'true' or 'false' accordingly.

To distinguish autosave vs. explicit user requests to save, the following
header:

    X-LOOL-WOPI-IsAutosave

will have the value 'true' when the PutFile is triggered by autosave, and
'false' when triggered by explicit user operation (Save button or menu entry).

Detecting external document change
----------------------------------

The locking part of the WOPI protocol is left out, because it goes against how
the files are being used in many EFSS solutions.  Instead, LibreOffice Online
uses timestamps to detect document changes.

When the document is updated in your storage while being edited in LibreOffice
Online and there are unsaved changes, we detect it as soon as possible and ask
the user if he/she would like to overwrite the changes or reload the new
document from the storage.

In case there are no unsaved changes, we reload the new document without
asking the user.

To support this feature, wopi host implementation has to specify
LastModifiedTime field in both CheckFileInfo and PutFile calls.

Additionally, WOPI hosts must check for a header in PutFile response:

    X-LOOL-WOPI-Timestamp

This header contains the ISO8601 round-trip formatted time of file’s last
modified time in storage, as known by LibreOffice Online. In case this header
is present and its value does not match the file’s modified time in storage,
it indicates that document being edited is not the one that is present in the
storage.

WOPI hosts should not save the file to storage in such cases and respond with
HTTP 409 along with LibreOffice Online specific status code:

    HTTP 409 with JSON:
    {
        “LOOLStatusCode”: 1010
    }

When the user chooses "overwrite" when asked how to resolve the conflict,
LibreOffice will attempt one more save operation, but this time it will lack
the X-LOOL-WOPI-Timestamp header, which means "save regardless of state of the
file".