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 a WOPI-like protocol to interact with hosts who
want to integrate LibreOffice Online in them.

Refer to WOPI docs[https://wopi.readthedocs.io/en/latest/] for further
details on the protocol's inspiration.

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

BaseFileName
	A string containing the basename of the file, omitting its path.

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

OwnerID
	A programmatic string identifier for the owner of the file.

PostMessageOrigin
	A string for the domain the host page sends/receives
	PostMessages from, we only listen to messages from this domain.

Size
	Size of the file in bytes (64bit)

UserCanWrite
	A boolean flag, indicating whether the user has permission
	to edit and/or over-write the file. If not set PutFile will fail.

UserCanNotWriteRelative
	A boolean flag indiciating that the user cannot Save-As on
	this server, so PutFileRelative will fail.

UserId
	A programmatic string identifier of the user.

UserFriendlyName
	A string representing the name of the user for display in the UI.


CheckFileInfo extended 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

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 other 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 protocol 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
----------------------------------

Locking is omitted from our WOPI-like protocol since it goes against
common EFSS solutions usage. 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, the host implementation has to specify
LastModifiedTime field in both CheckFileInfo and PutFile calls.

Additionally, 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.

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".