ONLYOFFICE 7.0: online forms, password protection in sheets, collaboration improvements and much more
ONLYOFFICE 7.0 released

How to manage document.key correctly?

Hi folks,

I’m trying to integrate online editors into my application. The thing is, I’m very confused with the document.key property. I’ve read the documentation.

In the troubleshooting page (ONLYOFFICE Api Documentation - Troubleshooting), it says: “Do not forget that every time the document is edited and saved, the document.key must be generated anew”

In document config page (ONLYOFFICE Api Documentation - Config) it says: “Every time the document is edited and saved, the key must be generated anew. The document url can be used as the key but without the special characters and the length is limited to 128 symbols.” In same page, it also says: “The key characters can be used: 0-9, a-z, A-Z, -._=. The maximal key length is 20 characters”. So idk if it should be 128 or 20 characters at maximum.

Here is my use case:

  • In the beginning, a user creates an empty docx file, lets say {guid}.docx, I’m using same guid as document.key property at first (without {}, lets say 1be4a90d-e253-4cd5-8db6-3ca964edcddd.docx)
  • The person who created the document, writes some text into the document, everything is saved automatically.
  • The person invites other users to edit this document. At this point, I change document.key value to, lets say, 1be4a90d-e253-4cd5-8db6-3ca964edcddd-0.
  • Other users opens this document and able to work together.

This “invitation” is async process in my app. Anyone can join to edit document any time. So if I change document.key for every person who opens a document, they fail to work together. Everyone is editing their copies, not working together.

Lets say 2 people are editing document with guid-0 key value, how can I detect they when all users quit the document so I can update key value to set guid-1 for newcomers? Apparently I can’t change this value in random times, especially when someone is editing the document at that specific time.

I’m also confused with this sentence: “Every time the document is edited and saved, the key must be generated anew”. In co-editing mode, document is saved in all keystrokes by all users, right? So I can’t decide when to update.

Thanks for help!

Document server version: 6.4.2
OS: Windows Server 2019
Browser: Chrome / Edge / Firefox

Hello @hasangok
Please let me describe it in detail.

“Every time the document is edited and saved, the key must be generated anew” – that means the final save of a file (when editing session is closed, i.e. all users left a file). By the way, if you are using forcesave feature, you should use the original (same) document.key.

Please check it out: https://api.onlyoffice.com/editors/coedit

Co-editing feature is possible due to using the same key only. When\how to change this parameter is your task as the integrator. For example, you can do it when editing session is closed or is started (file opening).

I’m also confused with this sentence: “Every time the document is edited and saved, the key must be generated anew”. In co-editing mode, document is saved in all keystrokes by all users, right? So I can’t decide when to update.

No, while editing session is in progress, all changes which were made by users are stored on document server side (database and cache). These changes are built to new file version and are sent to a storage only when editing session is over (or when forcesave feature is run).

Lets say 2 people are editing document with guid-0 key value, how can I detect they when all users quit the document so I can update key value to set guid-1 for newcomers?

Please check it out: ONLYOFFICE Api Documentation - Callback handler
“status 2” means that editing session is over and a file is ready for saving. That means all users left the file.

Hi @Alexandre,

Thanks for your explanations, it is more clear for me now. I have to “force save” document when the last editor leaves the window, for that I must know who are editing the document that specific moment.

I have a question for that case too. In the faq page there is a question for that need: How to find the information about users who are currently editing the document? And there is a github issue here saying that faq page was not clear enough. Could you please assist me to make proper call to retrieve users, so that I know exact time when the last editor leaves and forceSave the document and update document.key value.

Thank you very much.

Hello @hasangok
No, it’s not about forcesave command when editing session is closed. Forcesave and end of editing session have different callback statuses - “6” and “2”.
So, you should track status ‘2’ to check that editing session is closed.
If I misunderstood your question, please clarify it.