This documentation relates to an old version of the Nuxeo Platform (5.5). You may want to check the latest technical documentation.

Versions Compared

Old Version 2

changes.mady.by.user Laurent Doguin

Saved on

compared with

New Version 3

changes.mady.by.user Solen Guitter

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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" (smile)

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.

Outlines

Here is basically a quick overview of the WSS logic:

Negotiation phase

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:

  • users
  • tasks
  • links
  • 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...

Implementation choices

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 (smile)

Root binding

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).

General design

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)

SPI

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

Test env

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

Setup

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:

Code Block
xml
<filter>
        <display-name>WSS Filter</display-name>
        <filter-name>WSSFilter</filter-name>
        <filter-class>org.nuxeo.wss.servlet.WSSFilter</filter-class>
        <init-param>
            <param-name>org.nuxeo.wss.rootFilter</param-name>
            <param-value>/nuxeo</param-value>
        </init-param>
    </filter>
    <filter-mapping>
        <filter-name>WSSFilter</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

NB: the wss-handler jar needs to stay in $JBoss/server/default/lib
(no need to deploy it inside Nuxeo)

Step 2

Deploy nuxeo-platform-wss-backend in nuxeo.ear/plugins/

Accessing

You should be able to create a WebFolder or to open from MSOffice using:

Limitations of the model

WSS model is closer to a filesystem than to an ECM System.

Basically:

  • 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.

Known bugs

  • 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