Form Submit

Tags:  

Form Submit (multi-part)

In order to push the document from enterprise server and load it onto Zoho Services (Writer/Sheet/Show) editor, you need to submit a multi-part form-data to Zoho Services Grid with the following parameters. These parameters are common for all the three Zoho Services - Writer, Sheet and Show.

Parameter Value
Type
Description
content
string
Optional
Actual content of the uploaded document. A new document will be created, if the content is empty.
apikey
string
Mandatory
Uniquely identifies the web-application in which the Zoho Service editors are integrated.
output string
Mandatory Determines the format in which the Zoho Service output will be sent.

Possible values : view, editor, viewurl, url
Default value : url
filename
string
Mandatory Name of the document with proper file extension.

Supported values for documents : doc, docx, rtf, odt, htm, html, txt
Supported values for spreadsheets : xls, xlsx, ods, sxc, csv, tsv
Supported values for presentations : ppt, pptx, pps, ppsx, odp, sxi
lang
string
Optional
Lang parameter enables each Zoho Service (Writer/Sheet/Show) to offer its remote editor interface in another language.

Default value : en (English)

For a full list of languages supported by Zoho Service remote editors, please click here.
id
string
Mandatory
Mandatory. Unique handback id or doc session id that integrators/users need to provide when sending request to Zoho for opening a particular document. 

The 'id' parameter can be used to store all relevant document-related information, including session id, list of shared users, doc id etc. as an encoded string.

The info in 'id' parameter will be returned to the 'saveurl' by Zoho Document Servers whenever 'save' is invoked by the user.

Use-case: By providing shared user info in the 'id' parameter, a developer or a saveurl handler of the Zoho-integrated application will get to know which shared user has saved a document during collaboration.
format
string
Mandatory
The format in which the document needs to be saved back to the enterprise document repository.

Supported values for documents : doc, docx, html, pdf, htm, odt, rtf, txt
Supported values for spreadsheets : xls, xlsx, ods, sxc, csv, tsv, pdf
Supported values for presentations : ppt, pptx, pps, ppsx, odp, sxi

Note : The document can be pushed from enterprise server to Zoho Service editors in one format (say doc) and saved back to their original location in different format (say pdf).
persistence
(deprecated)
boolean
Optional persistence = true has been deprecated and the default value of this parameter is now set to false.

This means, a copy of the document will temporarily reside on Zoho's document servers as long as you have the document open in Zoho editor. After you save & close the document session, the copy is automatically removed from Zoho's document servers. 
 
saveurl* string Mandatory [Enterprise Server Web URL] - The saveurl 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 location specified in enterprise document repository.

Note : The saveurl, specified either over https or http url scheme, should be a public accessible, proper domain name with its port set to 443 or 80. Setting IP Address as saveurl value is not advised and will return an error.

Also, please ensure that the value provided for the 'saveurl' parameter is without spaces. Saveurl value containing spaces will throw an error and the file will not get saved.

Example - https://example.com/docs/save.php. 
agentname*
string
Mandatory
Name of the remote agent that is required to notify save operation.
username
string
Optional Name of the user opening the document.
documentid
long integer or (string returned by Zoho)
Optional
Unique Id of the document for identification purpose. In case of user failing to provide a documentid, Zoho Servers will generate one automatically as an encrypted string.
skey (deprecated)
string
Optional The secret or secure key value that needs to be passed for accessing Zoho editor urls over https.

Note: Use only the 'api key' parameter to access Zoho Services over https.
mode
string
Mandatory Defines access privilege for the user when opening the document in Zoho Service editors.
Possible values : view, normaledit, collabview, collabedit

view -- Document opens in read-only mode

normaledit -- Document opens exclusively in edit mode for the user and no other collaborator is allowed

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 user can edit the document at the same time.

Sample Form
<form method="POST" action="https://writer.zoho.com/remotedoc.im" enctype="multipart/form-data" target="_self" 
accept-charset="UTF-8">
File : <input type="file" name="content" size="38"> <br>
<input type="hidden" name="apikey" value="[Zoho_API_Key]">
<input type="hidden" name="output" value="url">
<input type="hidden" name="filename" value="mydocument.doc">
<input type="hidden" name="id" value="12345678">
<input type="hidden" name="format" value="doc">
<input type="hidden" name="saveurl" value="[https://xyz.com/docs/save.php]">
<input type="hidden" name="agentname" value="ZRemoteAgent">
<input type="hidden" name="username" value="JohnDoe">
<input type="hidden" name="documentid" value="57437534133099">

<input type="hidden" name="mode" value="[view/normaledit/collabview/collabedit]">
<input type="submit" name="submit" value="Open/Edit">
</form>
Note : Users need to pass either the agentname or the saveurl parameter when doing a form submit. If both the parameters are given,
agentname takes precedence, overriding the saveurl parameter and remote agent pull mode is enabled.
 
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 enterprise's remote server. This is a servlet call which returns "documentid", "isPresent" and "collaboratorsCount" as a response.

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

Request:

Parameter Value
Description
api key
string
Mandatory. Uniquely identifies the web-application in which the Zoho Service editors are integrated.
doc
integer          
Mandatory. Unique id of the document (documentid) either provided by the enterprise application or sent by Zoho.

For writer/sheet/show - https://<writer/sheet/show>.zoho.com/remotedocStatus.im?doc=<docid>&apikey=<apikey>      
Response:

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

 {"result": {"docid":"9765","isPresent":"true","collaboratorsCount":"4"}}  
Parameter Value
Description
docid
integer
The document id sent by the user.
isPresent
boolean          
true - if the document is available
false - if the document is not available
collaboratorsCount
integer
Count of the number of collaborators working on the shared document

Contact Us

If you have any further technical questions regarding Zoho Remote API, write to us at api-support@zohocorp.com.

    Post a comment

    Your Name or E-mail ID (mandatory)

    Note: Your comment will be published after approval of the owner.




     RSS of this page