|
|
|
|
Zoho Remote API - Enhanced
The enhanced version of Zoho remote api brings in the best of both the worlds for enterprises and small & medium sized businesses - collaboration capabilities of an online application while keeping the data safe behind their firewall. Earlier enterprise remote servers had to expose one of
their ports from their location so that Zoho Services can push the data back.
Instead, we now provide a remote agent that you need to install inside your
firewall. The remote agent basically pulls data from the Zoho Services to
your servers, once the document content is edited and saved back.
The list of features available with the enhanced version of Zoho Remote API are :
- Creation of new document/spreadsheets/presentations.
- Collaboration on existing as well as new documents by shared users.
The collaboration feature of Zoho productivity applications responds to the basic human need to connect with others - share a document with others & allow them to work on it. When you share a document, you give others access to that document so that they can view it or, if you prefer, work on it with you. And all in real time — so when someone makes a change, the document gets updated for everyone. What's more, Zoho's built-in chat allows you to see who else is editing the document at that time and interact with them in real-time.
Implementing Enhanced Remote API - The Basics
With the introduction of collaboration feature in the enhanced version of remote api, there are a few parameters that users need to understand before getting started with the implementation. The prominent among them are :
documentid :
The document id, as the name suggests, is the unique id of a particular document and is used for identification purpose. Users should provide the documentid parameter value as long integer (max. 16 chars). In case of user failing to provide a document id during form submit, Zoho Servers will generate one automatically in form of an encrypted string. When a document is uploaded to Zoho editors for editing, a unique & encrypted document url is assigned to it and that document url is persisted with till 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 case of collaborative edit or view mode where multiple users can be working on the document at the same time, the document url will be active till 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 only be unique for that API Key. In case a user provides a document id that has already been used earlier, we will load the existing document into Zoho's editors. In other words, a document id can be similar across different API Keys, but it should be unique for a specific API Key.
agentname :
The name assigned to Zoho's remote agent that is installed on the enterprise servers behind their firewall. The remote agent acts as a link between the enterprise web portal and
the Zoho Service editors. It basically handles all the tasks right from
uploading the documents to Zoho Service editors, to saving the edited
content back to enterprise document repository. A visual work-flow of the remote agent architecture and its saving mechanism can be found here.
Note : For enterprises who wish to work with remote apis without the firewall intervention, there's another saving mechanism that doesn't require installation of remote agent. All they need is to specify the location, where they want the document to be saved, in the saveurl parameter while doing a multi-part form submit. Detail architecture of the saveurl work-flow can be found here.
skey :
The secret or secure key value that needs to be sent along with the request for accessing Zoho editor urls over https.
Currently, Zoho supports the CAs (Certification Authority) that are part of Sun's JRE list. Full list is available here. Partners need to ensure that before purchasing a certificate, they have to check whether their certification authority (CA) is part of Zoho's list of supported CAs. SSL access will work only if the root CA or intermediate CA is from one of the listed CAs.
mode :
The mode parameter determines the manner in which the user would like to upload his document on 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.
Enhanced Remote API - Components & Functionality
The components as well as the Zoho services, involved in enhanced remote api
implementation, for enterprises are listed below :
- Zoho Remote Agent
- Zoho Services
Zoho Remote Agent
For
enterprises who wish to access Zoho Services' editors from behind their
firewall, need to have a Zoho Remote Agent installed in their servers.
As discussed briefly, the remote agent, installed inside the enterprise server, is central to the way the document content is pushed to Zoho editors for editing & collaborative purposes. In addition to this, the remote agent is also responsible for saving the content back to enterprise document repository as well as notifying the Zoho server of the same. The list of tasks are
explained in details below :
Document Push
- User opens the document from its enterprise portal.
- Enterprise server pushes document to Zoho Services Grid.
- Zoho Services Grid converts and sends the code to be loaded in the browser.
The enterprise server needs to submit a multi-part form post, in order to push the document to Zoho Service editors. Technical details of the form post can be found in the url here -- http://api.wiki.zoho.com/Form-Submit.html
Document Open / Edit
- Enterprise Server opens the Zoho Services code in client end.
- Based on the file type (doc, xls, ppt etc), Zoho Writer, Zoho Sheet or Zoho Show editor will open the document in browser.
- Enterprise client requests and establishes a message connection to WMS (Web Messaging Service).
Document Save without Firewall
For
enterprises who choose to save the document without any firewall
intervention, can do so by specifying saveurl parameter value in the form submit. A saveurl is nothing but a publicly accessible web url that
fetches the content of the updated document from Zoho Document Server
and saves it to the location specified in the enterprise document
repository.
- User clicks on save button from Zoho Service editor and sends a request to Zoho Document Server.
- Zoho
Document Server receives a Save request and pushes the updated document
content to the location specified in saveurl parameter.
- The enterprise web app in turn notifies the Zoho Document Server that save is successfully done.
Document Save with Firewall
- After the requisite editing done to the document, user clicks on save link/button from Zoho Service Editor.
- Zoho Document Server receives a Save request and in turns sends a message to WMS Grid notifying about the Save operation.
- Message is then sent to the Remote Agent from WMS Grid for Save Call
- Once the message is received, Remote Agent pulls the edited document from Zoho Document Server to enterprise document repository.
Save Notification
- Notification about document save is posted from Remote Agent to Zoho Document Server.
- Zoho document server in turn notifies WMS.
- WMS
notifies user's web browser about the save operation. The user web browser shows the
success message that save is completed.
Sample Code - Remote Adapter Interface
This is for enterprises who have opted to make use of the remote agent behind their firewall and are passing "agentname" parameter in the form submit.
We will be providing the enterprises with a remote adapter interface.
The interface will be part of the remote agent that is installed behind
their firewall.
The remote adapter interface basically handles
the saving mechanism of documents, spreadsheets, presentations in
enterprise document repository. A sample code of how a remote adapter
will look like, is given below for reference :
package com.zohocorp.remoteagent;
import java.util.Hashtable;
import java.io.File;
import java.io.FileOutputStream;
public class RemoteAdapterImpl implements RemoteAdapter
{
public String handleZohoDocument(Hashtable info, byte[] content)
{
//your implementation for saving the document goes here. below is the sample
System.out.println(""+info);
FileOutputStream fos=null;
try
{
String format = ""+info.get("format");
if(format==null){format="doc";}
File f = new File("writer."+format);
fos = new FileOutputStream(f);
fos.write(content);
fos.flush();
fos.close();
return "Document Saved Sucessfully";
}catch(Exception e)
{
}
finally
{
try
{
if(fos != null)
{
fos.close();
}
}
catch(Exception ex)
{
ex.printStackTrace();
}
}
return "Unable to save the Document";
}
public String handleZohoWorkBook(Hashtable info, byte[] content)
{
//your implementation for saving the spreadsheet goes here. below is the sample
System.out.println(""+info);
FileOutputStream fos=null;
try
{
String format = ""+info.get("format");
if(format==null){format="xls";}
File f = new File("sheet."+format);
fos = new FileOutputStream(f);
fos.write(content);
fos.flush();
fos.close();
return "WorkBook Saved Sucessfully";
}catch(Exception e){ e.printStackTrace();}
finally
{
try
{
if(fos != null)
{
fos.close();
}
}
catch(Exception ex)
{
ex.printStackTrace();
}
}
return "Unable to save the WorkBook";
}
public String handleZohoPresentation(Hashtable info, byte[] content)
{
//your implementation for saving a presentation goes here. below is the sample
System.out.println(""+info);
FileOutputStream fos=null;
try
{
String format = ""+info.get("format");
if(format==null){format="ppt";}
File f = new File("show."+format);
fos = new FileOutputStream(f);
fos.write(content);
fos.flush();
fos.close();
return "Presentation Saved Sucessfully";
}catch(Exception e){ e.printStackTrace();}
finally
{
try
{
if(fos != null)
{
fos.close();
}
}
catch(Exception ex)
{
ex.printStackTrace();
}
}
return "Unable to save the Presentation";
}
public String handleAutoSaveDraft(Hashtable info, byte[] content)
{
//your implementation for enabling auto-save functionality goes here. below is the sample
System.out.println(""+info);
FileOutputStream fos=null;
try
{
String format = ""+info.get("format");
File f = new File("zoho_autosave."+format);
fos = new FileOutputStream(f);
fos.write(content);
fos.flush();
fos.close();
return "Document Saved Sucessfully";
}catch(Exception e)
{
}
finally
{
try
{
if(fos != null)
{
fos.close();
}
}
catch(Exception ex)
{
ex.printStackTrace();
}
}
return "Unable to save the Document";
}
}
|
Contact Us
If you
have any further questions regarding enhanced version of Zoho Remote API, write to us at
api-support@zohocorp.com.
|
Document Saved Successfully
|
|
|
|
|
|
|
