This page describes how WSS has been used in Nuxeo DM, since version 5.4.2 this has been replaced by the WebDAV support.
Windows SharePoint Services is a set of protocol that is used by Microsoft applications (mainly the Windows Explorer and MS Office) to access content stored inside a SharePoint Team Services site.
Target Scope of WSS implementation in Nuxeo
The target scope of this implementation is:
- Browse / Open / Save documents from MS Office 2003 / 2007
- Browse / Open / Save documents from Explorer if MS Office 2003 / 2007 is installed
- Display some meta-data informations in MS Office 2003 / 2007
Understanding the beast
WSS is not a complicated protocol, it's an aggregation of several protocols and different technologies.
In a lot of cases, finding the needed information was a complicated task.
Not because there is no documentation but because there is to much documents and that information is largely spread across several pieces.
Some may suspected this is done "on purpose"
The documentation mixes all aspects of SharePoint technologies:
- communicating from FrontPage to administer web sites
- communication between several SharePoint servers
- customizing SharePoint
- automating SharePoint
The point is that the really interesting part is what WSS clients (mainly Explorer and MSOffice) really use.
And on theses aspects it's not that easy to find precise informations about:
- error handling for a given method
- meaning of a meta-data in weermer-rpc
- how the client interpret and use the results
Development was started based on the documentation, but we quickly realized that:
- some points were not working as inside the doc
- some parts of the protocol are not useful / needed
So, quickly we fall back to using ngrep to dump dialogs between a Windows VM and a SharePoint server.
Not very fancy, but efficient.
Here is basically a quick overview of the WSS logic:
Client ask the server for capability and supported version.
At this point, the main "browsing protocol" is chosen: WebDav or FrontPage RPC.
FrontPage for browsing
Since WebDav for WSS seems to be droped for new versions of windows clients, we choose FrontPage RPC.
This is basically a simple HTTP protocol:
- method name is sent as a request parameter
- parameters are encoded (as QueryString, or as veermer encoding in the body)
HTML and JS for MSOffice WebView dialog
Open and Save dialogs for MSOffice are generated from HTML and JS is returned by the server.
There is some mystery on what part of the HTML and JS is actually used by MSOffice to make the dialog actually work.
For example the Open dialog worked very simply (based on a ngrep capture), but the Web Dialog for Save As never worked for a reason that is still unknown.
WebServices for Office Companion
The MS Office companion tool bar displays information about the data related to the workspace of the current open document:
- other documents
This panel is using some WebServices to fetch data from the server.
Strangely, one of the panel tabs always remains empty, even when communicating with a "real SharePoint server".
Please note that this is a simple view, some clients (like the WSS Mac client) do not exactly behave this way...
Make a generic handler
A big part of the work is about filters, handlers and marshalers: nothing fancy or fun.
We wanted to have this code as generic as possible in order to be reusable and not bound to the Nuxeo framework.
For most protocol handling part, that mainly depends on Servlet API, this is not really an issue.
It was more painful for managing configuration and pluggability: Extension Points were missing
Surprisingly, WSS protocol needs to communicate with the root of the server.
Some part of the negotiation protocol can lead to think there was a way to limit root calls to only one, but it did not work as expected.
So, some service calls have to be handled in the root servlet context.
This is a design constraint, because you must have code in both context, and in some cases, it has to be the same code (same call on root and on Nuxeo context path).
Generic protocol handler
The generic handler is mainly composed of:
- a main filter
- handlers for each protocol (HTTP, FP-RPC endpoints, WebService ...)
- handling marshaling and unmarshaling
- a proxy system (to handle and forward calls made to the root)
The generic handler calls a simple SPI to do the actual work:
- listing content
- checkout / uncheckout
- get meta-data on a document
- download / upload a file
For testing purpose, a dummy "in memory backend" is provided.
It allows :
- direct live testing of the generic handler
- unit testing of the handler (using ngrep capture as test input)
Use of freemarker
Most WSS response handling is about HTML formatting.
For all this work FreeMarker was used since it is already bundled with Nuxeo.
Dummy WebService implementation
When testing WSS it appears that :
- very few calls are indeed needed
- most of them return a XML results encoded in a SOAP envelop
So, current implementation does not include a real WebService stack, and simply uses FreeMarker.
Using WSS in Nuxeo
Nuxeo backend for WSS
In order to test WSS against Nuxeo, you have two configurations to make:
- setup the root filter and set it in proxy mode
- deploy the nuxeo-wss-backend
Step 1 can be done in the root web.xml by just adding the org.nuxeo.wss.rootFilter param:
NB: the wss-handler jar needs to stay in $JBoss/server/default/lib
(no need to deploy it inside Nuxeo)
Deploy nuxeo-platform-wss-backend in nuxeo.ear/plugins/
You should be able to create a WebFolder or to open from MSOffice using:
- http://server:8080/nuxeo/ : to access directly Nuxeo
- http://server:8080/ : to access directly server root
Limitations of the model
WSS model is closer to a filesystem than to an ECM System.
- a document is a file
- document title (display name) = name (URL part)
- checkout system is very simple
In a lot of cases, Nuxeo DM offers much richer features, but they won't be accessible via WSS because the model does not permit that.
Furthermore, only very basic features of WSS are accessible via MS Office and Explorer: the simple filesystem operations.
- since Nuxeo separates title and names and WSS does not, renaming from WSS can sometimes not work as expected
- delete from Windows Explorer displays an error but works
(and response from Nuxeo server seems OK, but client does not like it...)
Using Generic Handler for your application
You can use Nuxeo WSS Generic Handler to provide WSS access to your application.
For that you should:
- implement SPI
(cf package org.nuxeo.wss.spi)
- override templates if needed
(templates defined in the backend override the default one)
- configure the filter to use your backend