List of Developer FAQs for the Zoho Integration
Zoho Remote API allows for partners to create, edit and collaborate on their documents in Zoho's Office productivity service editors (Writer, Sheet, Show) while at the same time offering its partners to store and manage these documents on their own servers. With Zoho Remote API, you can:
- Create a new document, spreadsheet & presentation from your web application
- Open existing documents.
- View and Edit documents based on the access privileges defined by the administrator of your web application.
- Collaborate on the documents in real-time.
- Save the document content back to your document servers.
1. How do I open documents in Zoho Service Editors?
Zoho Service Editors, exposed through Remote APIs, can be invoked by doing a simple HTTPs POST request to the specific Zoho Service URL. Depending on the file location, local drive or web, developers can send the request to Zoho Servers for opening the document in a couple of ways:
As for sending request to Zoho Service URLs, developers can use the below links based on the file type (.doc, .xls, .ppt etc):
- Zoho Writer (document) - https://writer.zoho.com/remotedoc.im
- Zoho Sheet (spreadsheet) - https://sheet.zoho.com/remotedoc.im
- Zoho Show (presentation) - https://show.zoho.com/remotedoc.im
2. Can I access my documents in Zoho Service Editors over secure connection (https)?
Yes. For added assurance of accessing Zoho Services over a secure connection (https), developers need to pass an additional 'skey' parameter during form submit. The 'skey' value is associated with your 'api key' and can be obtained from the API Dashboard. You can log in from the API Sign-in page (https://zapi.zoho.com) with your Zoho account credentials (username/password) to get the 'skey' details.
Also, change the Zoho Service URL scheme to https when sending the form request. Example: https://writer.zoho.com/remotedoc.im
3. I get an error while saving a document over https URL scheme. What am I doing wrong?
The stated error in saving the document will occur in any of the below two cases:
SSL Certificate does not match your registered domain name. Check the authenticity of your SSL Certificate from the website - http://www.digicert.com/help/
Partner's SSL Certificate is not part of the Sun's JRE list supported by Zoho. List of supported CAs(Certification Authority) can be found here.
4. How do I open document in different modes (view/edit) in Zoho Service Editors?
There is a 'mode' parameter that determines the way in which the document is uploaded to Zoho Service Editors. 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, no other collaborator is allowed for concurrent editing.
- collabview -- Document opens in collaborative view mode. Multiple users can view the contents of the document at the same time and can leave notes/comments using the integrated chat service. However, they cannot edit the document content.
- collabedit -- Document opens in real-time collaborative edit mode. Multiple users can edit the document as well as add notes/comments at the same time.
Note: It is mandatory to set the output parameter value as 'url' when mode is chosen as 'collabedit' during form submit.
5. What is the use of 'output' parameter? How is it different from 'mode' parameter?
The 'output' parameter decides the format in which output is sent from Zoho Servers. This is in response to the request sent by partners' server for opening the document. The response for the output could be either in 'url' or 'editor' format.
Note: For Zoho integration, we recommend using 'url' as the output parameter and send the request as an emulated multi-part form
(HTTPs POST) from the partner's server. The 'editor' value can be used for testing purpose from the client-end.
List of output parameter values are:
- url -- Zoho sends the response in the form of url. Use this document 'url' in the web-browser for opening the document in Zoho for editing purpose.
- viewurl -- Response in url format. Document opens for viewing only.
Important Note: With the introduction collaboration feature in Zoho Remote API, we have added a new 'mode' parameter. This 'mode' parameter has now taken precedence over the 'output' parameter. The value provided in the mode parameter over-rides that of output parameter in few of the use-cases. These are described below:
|1||null||null||Writer - Doc opens in 'normaledit' mode|
Sheet - Doc opens in 'view' mode
Show - Doc opens in 'view' mode
|2||null||view||Document opens in 'view' mode|
|3||null||normaledit||Document opens in 'normaledit' mode|
|4||null||collabedit||Document opens in 'collabedit' mode|
|5||null||collabview||Document opens in 'collabview' mode|
|6||url||null||Document url returned which opens in 'normaledit' mode|
|7||viewurl||null||Document url returned which opens in 'view' mode|
|8||editor||null||Document opens in 'normaledit' mode|
|9||view||null||Document opens in 'view' mode|
|10||url||view||Document url returned which opens in 'view' mode|
|11||url||normaledit||Document url returned which opens in 'normaledit' mode|
|12||url||collabedit||Document url returned which opens in 'collabedit' mode|
|13||url||collabview||Document url returned which opens in 'collabview' mode|
|14||viewurl||view||Document url returned which opens in 'view' mode|
|15||viewurl||normaledit||Document url returned which opens in 'normaledit' mode|
|16||viewurl||collabedit||Document url returned which opens in 'collabedit' mode|
|17||viewurl||collabview||Document url returned which opens in 'collabview' mode|
|18||editor||view||Document opens in 'view' mode|
|19||editor||normaledit||Document opens in 'normaledit' mode|
|20||editor||collabedit||Document opens in 'collabedit' mode|
|21||editor||collabview||Document opens in 'collabview' mode|
|22||view||view||Document opens in 'view' mode|
|23||view ||normaledit||Document opens in 'normaledit' mode|
|24||view||collabedit||Document opens in 'collabedit' mode|
|25||view||collabview||Document opens in 'collabview' mode|
6. If I pass in collabedit for 'mode', how do I point another user at it for concurrent editing?
First of all, you need to set the output parameter value as 'url' before sending the request to Zoho Servers via HTTPs Form POST. When you do the form post for 'User A' with output as 'url' and mode as 'collabedit', you will get a response in return with the documentid and it will be something similar to the one below:
WARNING=NULL RESULT=TRUE DOCUMENTID=4uaWNZ7T4738yaIcy5UxMN6/F4Vd
Now, use the above 'DOCUMENTID' and do the HTTPs Form POST again for the 2nd user (say User B). You can provide a name for the shared user in the 'username' parameter for easier identification of collaborators. Once you get the response as the document url, you can ask 'User B' to provide the doc url in the browser address bar, press enter and join 'User A' in collaborative editing mode. Similarly, invite more users to work on the document by providing the same documentid in subsequent requests.
7. Why do all the shared users in collaboration mode are listed as 'Guest'?
By default, Zoho Servers identify collaborators as 'Guest' in case no username is given. For easier identification of the shared users in collaboration mode, we recommend developers to make use of the 'username' parameter, and provide names of the collaborators, when sending the request to Zoho. Once the collaborators start working on the shared document, their names will get listed on the integrated Chat panel. Each shared user can see the other co-editors by clicking on the 'Collaborators () ' button present in the status bar of the document editor.
Moreover, the paragraph or the section of the document on which User A does the edit is color-coded and hence its easy for User B to identify which part of the document is being edited by his co-editor.
8. What is the maximum file size I can upload to Zoho?
A single document uploaded to Zoho's Office Editors (Writer, Sheet & Show) has a file size limit of 12 MB. In case you are trying to upload a document that is greater than 12 MB, the request will fail and you'll get a timeout error as a response from Zoho.
9. What is the 'id' parameter used for? Is it mandatory?
The 'id' parameter, also known as handback id, can be used by developers to pass additional information on the document when sending the request to Zoho. The doc-related info in the 'id' parameter will be returned by Zoho to the partner's document repository every time a 'Save' is invoked from the Zoho Service Editors. Few use-cases:
- Get to know who has saved the document in collaboration mode.
Assign shared user information as 'JSON/XML' string in the 'id' parameter value. Zoho will return the details on which user has saved the document in collaboration mode.
- Any document related information that is required by the web application. This may include file type, file id, folder id where the doc needs to be saved etc.
Note: The 'id' parameter is mandatory and accepts 'string' value as an input. An error will be thrown if the parameter is missing.
10. Every time I send a request to Zoho, I receive 'Unable to Import Content' error? What am I doing wrong?
You will get the 'Unable to Import Content' error in either of the two cases:
- The document format is not supported by Zoho. For a full list of support file formats click here.
- Zoho is unable to resolve the file extension in the request.
To get around this problem, you need to provide a filename with proper file extension (e.g. test.doc, sample.xls etc.) in the url parameter when doing a normal-form submit. Also, ensure the 'filename' parameter contains the name of the file with the original file extension of the imported document (e.g. test.doc).
11. When saving the document, I get junk characters in file name . Why?
The reason for receiving junk characters in file names can be attributed to:
- The file name is in language other than English (e.g. German, Chinese, Japanese etc.)
- The file name contains some special characters.
To offset this problem of junk characters, developers can encode the file names using the 'UTF-8' character encoding mechanism. UTF-8 or Unicode is a universal character set option that support multilingual documents, i.e., documents whose file name or content are written in various languages (Chinese, Japanese, German etc.) other than English.
So, developers have to give 'accept-charset="UTF-8"' value while doing a Form Submit using HTTPs POST method.
12. Can I use Zoho API for writing documents in multiple languages? If so, how many different languages does Zoho support?
Yes, you can make use of Zoho Service Editors for writing documents in various languages. All you need to do is pass a parameter named 'lang' with appropriate value during form submit.
Currently, Zoho offers its remote editor interface in more than 20 languages. For a full list of languages supported by Zoho Service editors, please click here.
13. When saving the document, I get a 'Connection refused from remote server' exception. Why?
Users will get this error when Zoho is unable to reach the partner's document repository path specified in the 'saveurl' parameter. One of the reasons could be that the document title contains spaces and the 'saveurl' value is not URL-encoded. Please URL-encode the 'savurl' parameter value to avoid this exception.