Integrating a CMIS repository with Zoho using gadgets in GateIn
1. Introduction
Content Management Interoperability Services (CMIS) is a standard for improving interoperability between Enterprise Content Management systems. It’s a new standard to make Document Management more interoperable.
A year and half ago, I already wrote a web service in java to edit documents, stored in the JCR, with Zoho. As CMIS arrive, it seems a good idea to rewrite this one with this standard and using groovy. Last time, I used a greasemonkey script to integrate it in eXo ECM, but this time, I’m going to create a gadget for that. Thanks to GateIn Gadget Dashboard, I’ll be able to follow multiple repository in one page and edit their files.
Requirements for this project
- Browse the CMIS repository
- If file can be edited with Zoho, offer this possibility
- Work in the main browsers
- Work with all the public CMIS demo servers available
What you need to know before starting
- Basic knowledge of the gadget API. If you don’t have a look at the Gadget Developer Guide
- Basic knowledge of javascript and jQuery
- Basic knowledge of what is Atom, REST and CMIS
2. Accessing to files of a CMIS servers
CMIS servers make available 2 types of API: SOAP and Atom. From javascript, it’s easier to use the Atom API. But all the browsers don’t handle namespaces the same way, so it makes it harder to parse response. We are going to use JQuery because it makes things easier than using the native javascript functions, but I guess it’s possible to do the same with YUI, Dojo or other…
Parsing Atom in Javascript
To get a namespaced node with jQuery, you can do:
//this doesn't work because the : is used by the selector syntax of JQuery var vendor = $(xmlNode).find("cmis:vendorName").text(); //this work in IE and Firefox but not in Webkit (Chrome and safari) var vendor = $(xmlNode).find("cmis\\:vendorName").text(); //This is going to work on IE, Webkit (Chrome and safari) and Firefox. var vendor = $(xmlNode).find("[nodeName=cmis:vendorName]").text();
So with this, I created a simple CMIS response parser in javascript: jquery.cmis.js (jsDoc). It can parse a Service, a Feed or an Entry.
To get the workspaces from a service:
//We parse the response sent by the CMIS service var workspaces = CMIS.parse(XMLDocument); //We take the first workspace var current_workspace = workspaces[0]; // show the vendor of the first workspace alert(current_workspace.getVendorName()); // Get the url pointing to the root directory listing var root_feed = current_workspace.collections["root"];
To list a feed’s entries:
//We parse the response sent by the CMIS service var feed = CMIS.parse(XMLDocument); feed.getEntries().each(function(i, entry) { // return if the entry is a folder if (entry.isFolder()) { // title of the folder entry.title; // get the link to browse the directory entry.getLinks("down"); } else { // title of the document entry.title; //URL of to get the content of the document entry.getContentUrl(); } }
Loading the feed from the gadget
So now that we know how to parse the response of a CMIS server. We can start building our gadget. Most (all?) the CMIS repository are using BasicAuth as authentication/authorization mechanism, so if our CMIS server is on the same domain name we could directly send a request to it. But as we want to be able to integrate CMIS server from all over the internet, we need to use a proxy (remember the same origin policy of our browsers).I’d love to see CMIS repositories to use oAuth authorization mechanism, but as it’s not the case for now, we need to write a simple proxy in Groovy and JAX-RS to do the authentication for us:
import javax.ws.rs.FormParam import javax.ws.rs.Path import javax.ws.rs.POST @Path("proxy") public class Proxy { @POST @Path("basic_auth") public String basic_auth(@FormParam("url") String url, @FormParam("login") String login, @FormParam("password") String password) { return get(url, login, password); } public static String get(String url, String login, String password) { // Basic Auth send login and password encoded in Base 64 in the header def encoded = "$login:$password".getBytes().encodeBase64().toString() def c = new URL(url).openConnection() c.setRequestProperty("Authorization", "Basic $encoded") return c.content.text } }
So to get a URL authenticated you can just call a url like this:
http://myserver.com/rest/proxy/basic_auth?url=http%3A%2F%2Fcmis.demo.nuxeo.org%2Fnuxeo%2Fsite%2Fcmis%2Fchildren%2F4fb1b8a1-6dfd-4da4-95b0-4ef41c27b920&login=Administrator&password=Administrator
From our gadget, to get the response of the CMIS server using our proxy, we are going to do:
var params = {}, prefs = new gadgets.Prefs(); postdata = { url: "http://cmis.exoplatform.org/rest/cmisatom", login: prefs.getString("login"), password: prefs.getString("password") }; // our proxy need a POST params[gadgets.io.RequestParameters.METHOD] = gadgets.io.MethodType.POST; // We want the response as a DOM Document params[gadgets.io.RequestParameters.CONTENT_TYPE] = gadgets.io.ContentType.DOM; // We encode our parameters params[gadgets.io.RequestParameters.POST_DATA] = gadgets.io.encodeValues(postdata); // And finally we send our request gadgets.io.makeRequest('http://cmis.exoplatform.org/rest/proxy/basic_auth', function(res) { if (res.rc == 200) { var response = CMIS.parse(res.data); // We can do now what we want with the response... } else { alert("Error: " + res.data); } }, params);
We can now just use our response object to list the files on our repository.
3. Editing the files with Zoho
Now that we have successfully accessed to our files, we would like to edit them with Zoho editor (API documentation). We have to POST the file to their server, and they return the URL to edit it. When the user will save the document, the zoho server will do a POST on a callback URL (defined on our first POST) containing the document.
You will need to get your zoho API key.
So, here is how it’s going to work:
- The gadget is going to call our service
- The service will download the file from the CMIS server
- The service will generate an ID for the document. We are going to use the URL on the CMIS server and the login/password to access it. To avoid sending the login and password to zoho, we could have store it in the JCR but it add an extra step that we are not going to show on this tutorial.
- The service will POST everything to the Zoho API corresponding to the right editor (Doc, spredsheet, presentation)
- The service will parse the response and return the url of the editor
- The gadget will redirect the user to the editor
- When the user save the document, Zoho will do a POST on our service to save it
- The service is going to push the document back on the CMIS server
It looks like a lot of things to do, but with groovy and JAX-RS it’s quite simple.
The gadget is going to call our edit service with the URL of the file and the credential needed in parameter:
@POST @Path("edit") public String edit(@FormParam("url") String url, @FormParam("filename") String filename, @FormParam("login") String login, @FormParam("password") String password) { //We prepare the request def client = new HttpClient() def ext = getExtension(filename) def postMethod = new PostMethod(getZohoURL(ext)) //Get the content of the file we want to edit and continue to construct the request for the Zoho server def src = new ByteArrayPartSource(filename, get(url, login, password)) Part[] parts = [ new FilePart("content", src), //content of the file we want to open new StringPart("filename", filename), // filename of the document with extension new StringPart("saveurl", callbackURL), //The Web URL should be a service that fetches the content of the updated document and saves it to the user specified location. new StringPart("id", getId(url, login, password)), //unique id that will be submitted while saving the document (for reference) new StringPart("format", ext) // the format in which document should be saved on remote server ]; postMethod.setRequestEntity(new MultipartRequestEntity(parts, postMethod.getParams())) try { // We send the request def statusCode = client.executeMethod(postMethod) // We transform the response into a hashmap def resp = parseResponse(postMethod.getResponseBodyAsString()) //if the status is not 200 (OK) or there was a problem in the opening of the file we throw an exception if (statusCode != 200 || resp["RESULT"] == "FALSE") { throw new WebApplicationException(Response.status(Response.Status.INTERNAL_SERVER_ERROR).entity(resp["WARNING"]).type("text/plain").build()) } //Everything went fine, so we return the URL to edit the file return resp["URL"] } finally { postMethod.releaseConnection() } } /** * from the extension of the file, find which endpoint calling */ private String getZohoURL(String extension) throws IOException { def url; if (extension == null) { throw new WebApplicationException(Response.Status.UNSUPPORTED_MEDIA_TYPE) } if (extension in ["doc", "rtf", "odt", "sxw", "html", "txt"]) url = "http://export.writer.zoho.com/remotedoc.im" else if (extension in ["xls", "sxc", "csv"]) url = "http://sheet.zoho.com/remotedoc.im" else if (extension in ["ppt", "pps"]) url = "http://show.zoho.com/remotedoc.im" else throw new WebApplicationException(Response.Status.UNSUPPORTED_MEDIA_TYPE) url = url + "?apikey=" + apiKey + "&output=url" return url; }
Now that we have sent the file to zoho, we need to save it back on the CMIS server. Zoho will call the following method:
@POST @Path("save") @Consumes(["multipart/*"]) public String save(Iterator<FileItem> items) { def stream def id // We loop over all the POST parameters to find the one that are interesting for us. while (items.hasNext()) { FileItem item = items.next(); if (item.getFieldName().equalsIgnoreCase("content")) { stream = item.getInputStream() } if (item.getFieldName().equalsIgnoreCase("id")) { id = new String(item.get()); } } // We are preparing the request to send to the CMIS server // This time, we are going to send a PUT to update the content stream def client = new HttpClient() def putMethod = new PutMethod(getUrl(id)) try { putMethod.setRequestBody(stream) putMethod.setRequestHeader("Authorization", "Basic " + getCredential(id)) putMethod.setRequestHeader("Content-Type", "application/octet-stream") def statusCode = client.executeMethod(putMethod) // if everything went fine, we return a message that will be shown to the user if (statusCode >= 200 && statusCode < 300) return "Saved" // If it did not go well, we send an error, and the user will be notified that something went wrong while trying // to save his document throw new WebApplicationException(statusCode) } finally { putMethod.releaseConnection() } }
We have now everything to be able to browse a CMIS repository and edit the files with Zoho. Have a look at the code of the final gadget and feel free to remix it. You can also view the demo on the xCMIS demo server. To deploy it in GateIn Beta5, read How to activate groovy REST services in GateIn Beta5.
4. Download and link to online demo
- The code of this example (Download)
- Demo with xCMIS, Alfresco and Nuxeo
- jquery.cmis.js(Download)
- xCMIS