Opening a file

In order to invoke the Zoho Office API and open a document in Zoho service editors, the developer needs to submit a request by way of a HTTPS POST form to the specific Zoho service URL. Depending on the file type (docx, xlsx, pptx), the request can be sent to the following URLs:

• Zoho Writer - https://writer.zoho.com/writer/remotedoc.im
• Zoho Sheet - https://sheet.zoho.com/sheet/remotedoc.im
• Zoho Show - https://show.zoho.com/show/remotedoc.im

Now, there can be a couple of ways of uploading the document to Zoho service editors via an HTTPS POST form. Depending on the location of the file (desktop or web) Partners can use either of the two methods:

1. Multi-part form submit - This is used for opening documents present in the partners' document management system.
2. Normal form submit - This is for opening documents that are present over a web URL and accessible by Zoho Document Servers.

Form Request Parameters Reference

Common Parameters

Following are the common parameters that need to be passed in multi-part and normal HTTPS POST request :

Specific Parameters

For multi-part form submit:

For normal form submit:

Output parameter values *

The output parameter decides the format in which the output is sent from Zoho document servers. This is in response to the request sent by the partner to open the document. Currently, Zoho allows four different values for the output parameter.

RESULT=FALSE
ERROR_CODE=3832
WARNING=The value specified for API key is invalid.

Error Messages

Saving a file

'saveurl' is a mandatory parameter. The save URL is a publicly accessible web URL which should be a service that fetches the content of the updated document from Zoho Document Servers and saves it to the partner document repository.

Also, please ensure that the value provided for the 'saveurl' parameter does not contain spaces. Save URL value containing spaces will throw an error and the file will not get saved.

Example - https://example.com/docs/save.php.

Note

• The saveurl specified over https/http URL scheme should be a public, accessible, proper domain name with its port set to 443/80. Setting IP Address as saveurl value is not advised. This will return an error.
• If you are using an https URL, please make sure that it complies with the list of certifications here.

Steps: Document Save and Notification

1. User clicks on save button from Zoho service editor.
2. Zoho Document Server receives a save request from the Zoho editors.
3. Zoho Document Server pushes the updated content to the partner save URL.
4. The partner's document management application in turn notifies Zoho Document Server that the save action is done successfully.
5. Document is saved back to the partner's repository.

Save Notification Messages

The partner's application can customize the save notification message sent to Zoho servers. The message is shown when the user saves the document from Zoho service editor and handles both the save cases:

1. Success Message (HTTP response code 200) - Sent when the document is saved successfully.
2. Error Message (HTTP response code 500) - Sent when the document save fails.

The response to be sent to Zoho servers is of the format:

RESPONSE: [Success or Failure Information message from the application]

Note : In case the partner application fails to provide a custom message of its own, Zoho will display its default save notification messages in the service editors. A list of these messages is given below:

Collaborating on a file

Document Collaboration with Zoho Office API

Zoho Office API supports real-time document collaboration. This means that several users can open a particular document at the same time, with everyone being able to contribute to the document in real time.

With the built-in collaboration features, an partner's portal can enhance user productivity, foster teamwork and cooperation. When a document is shared, teams can work together at the same instance. So when someone makes a change, the document is updated for everyone to see. In addition, the integrated Zoho chat application allows users to communicate with each other in real time.

Implementing Document Collaboration - The Basics

Before getting started with the implementation of collaboration features, partners need to know a few parameters and their definitions. The most important among them are:

Mode

The mode parameter determines the way in which the document gets uploaded to Zoho service editors for a particular user. Based on the access privileges defined by the partner/administrator for different users in a user group, they can either view or edit a particular document simultaneously. Currently, Zoho allows four different values that can be passed in the mode parameter. They are :

• view - Document opens in read-only mode.
• normaledit - Document opens in edit mode exclusively for the particular user. Collaboration will not be available.
• collabview - Document opens in collaborative view mode. Multiple users can view the document and leave notes/comments. However, they will not be able to edit the document.
• collabedit - Document opens in real-time collaborative edit mode. Multiple users can edit the document and leave notes/comments.

documentid

The document id, as the name suggests, is the unique id of a particular document and is used for identification purpose. The value of documentid parameter should be passed as a long integer from the user's end. In case the user fails to provide a document id during form submit, Zoho servers will generate one automatically as an encrypted string. When a document is uploaded to Zoho editors for editing, a unique and encrypted document URL is assigned to it. This document URL will persist as long as the document session is active. Once the user exits the document session, by closing or refreshing the browser tab, the document URL becomes invalid.

In the case of collaborative edit or view mode where multiple users may be working on the document at the same time, the document URL will be active until the last user exits the document session.

As you can see, Zoho generates a dynamic URL every time a document (new or existing) is uploaded to Zoho service editors. Therefore, it is recommended that users should leave the task of assigning the document id (encrypted) to Zoho instead of providing one for themselves.

Note : The document id provided here is associated with a particular API key and will be unique for that API key. In case a user provides a document id that has already been used earlier, Zoho will load the existing document to its editors. In short, a document id can be similar across different API keys, but it should be unique for a specific API key.

username

This is the name of the user who is opening the document in collaborative mode. Partners need to take care of the following when establishing a collaboration session for their users:

• Partner's remote server should provide the usernames in order to list the collaborators properly. By default, Zoho servers will identify collaborators as "Guest" if no username is given.
• They should explicitly mention the mode as "collabedit/collabview".
• In order to set up a collaboration session, all shared users should provide the same documentid.
• For subsequent collaboration sessions on the same document, partner's remote server should maintain the document id associated with it.

Note : It is mandatory to set the output parameter value as "url" when mode is chosen as "collabedit" during form submit.

Sample Response for collaborative editing in Zoho Office API

In collaborative editing mode, a documentid (optional) along with the document URL is returned to the user from Zoho servers. This means, several users can join the collaboration session by specifying this documentid and jointly view/edit the document. The response format will look like the one below:

RESULT = TRUE
URL = unique url
DOCUMENTID = encrypted unique docid

Remote Document Presence Status

The "remotedocStatus" API is used to check whether the document is already present in Zoho server or needs to be uploaded again from the partner's server. This is a servlet call which returns "documentid", "isPresent" and "collaboratorsCount" as a response.

If the "isPresent" value is returned as "false", partner can conclude that the document session is closed and is no longer available in Zoho servers.

Request

For Zoho Writer - https://writer.zoho.com/writer/remotedocStatus.im?doc=&apikey=Zoho_API_Key
For Zoho Sheet - https://sheet.zoho.com/sheet/remotedocStatus.im?doc&apikey=Zoho_API_Key
For Zoho Show - https://show.zoho.com/show/remotedocStatus.im?doc&apikey=Zoho_API_Key

Response

The response for the remotedocStatus is a JSON string and will look like the one below :

 {"result":{
                    "docid":"9765",
                    "isPresent":"true",
                    "collaboratorsCount":"4"
                     }}