[documentation] Detecting external document change: documentation not obvious about body of PutFile calls / difference between implementation in nextcloud/richdocument and doc

[julienfastre]

Describe the bug

On our implementation, we had problem with some document which could not be opened by collabora online. This was difficult to reproduce.

Comparing our implementation of detecting external document change and the implementation of nextcloud / rich document, I think there are some difference and misunderstanding that are, maybe, the cause of our troubles.

In details

The doc says that we should check for changes on the wopi host by using X-COOL-WOPI-Timestamp header.

It also says that:

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

This last sentence is not easy to understand regarding PutFile calls, as the WOPI protocol does not requires a body for PutFile calls: https://learn.microsoft.com/en-us/microsoft-365/cloud-storage-partner-program/rest/files/putfile

So, in our implementation, we left the body empty, and add a LastModified header on our response...

But:

• we encounter a error log in our collabora: collabora-online-app-1 | wsd-00001-19814 2023-01-09 14:39:44.145547 +0000 [ docbroker_e90 ] ERR Invalid or missing JSON in WOPI::PutFile HTTP_OK response.| wsd/Storage.cpp:1456
• further research about the implementation of wopi host in nextcloud / richdocuments make our realise a body is required: https://github.com/nextcloud/richdocuments/blob/master/lib/Controller/WopiController.php#L521

I think that we should re-write this part to add an exemple of expected body.

By the way, the implementation in richdocuments, the body in case of conflict is { 'COOLStatusCode': 1010 } in the doc, but { 'LOOLStatusCode': 1010 } in richdocument (the first letter is different).

To Reproduce

(difficult to explain here)

Expected behavior

When we read the doc, we should understand that a body is expected for PutFile calls.

Actual behavior

When reading the docs, it is not obvious that a body is expected on PutFile calls.

Desktop (please complete the following information)

Not relevant.

Smartphone (please complete the following information)

Not relevant

Additional context

Our implementation (with the problem fixed): https://github.com/Champs-Libres/wopi-bundle/blob/master/src/Service/Wopi/PutFile.php

EDIT add link and fix typo

[julienfastre]

I am volunteer to fix this issue. But I don't know where is the code for the doc deployed at https://sdk.collaboraonline.com/contents.html :smiley_cat: