Documentum’s Web Services Framework

I’ve recently spent some time taking a look at Documentum’s WSF (Web Services Framework).

New with 5.3, the WSF provides a mechanism for exposing BOF (Business Objects Framework) SBO’s (Service-Based Objects) as web services. This can provide a loosely-coupled way for other applications, regardless of their underlying platform, to work with Documentum.

The WSF is based on Apache Axis. Running the WSF installer installs Axis as a web application on a supported web application server, the DFC (Documentum Foundation Classes), and an encryption key.

Deploying an SBO as a web service

Exposing an SBO as a web service through the framework is pretty easy. The high-level process is:

  1. Develop the SBO;
  2. Package the SBO as you normally would according to BOF 2.0 deployment rules (i.e., separate your interfaces and implementation classes into two separate JARs);
  3. Use DAB (Documentum Application Builder) to create a new Module in a docapp and specify that the module should be a web service;
  4. Export the new version of the ws.war (created by the previous step), patch it with the URL to your WSF web application, and deploy it to your application server. (This is all covered in the WSF Development Guide).

As long as the interfaces don’t change you can simply check in new versions of the SBO via DAB when you need to make updates. If your interfaces change you have to repeat all of the steps so that the WSF web app will have the updated WSDL. (WSDL is XML that Eclipse or other tools use to automatically generate the client-side proxy classes against which you’ll code your client app).

You’ll want to check the WSF Development Guide for tips on how to make your SBO perform well as a web service. It may not be practical or preferred to simply take all of your existing SBO’s and use them as web services as-is.

Transferring content

When it is time to move content to or from the repository you have two choices for how that content is handled: Base64 or Documentum’s Universal Content Facility (UCF). There are other standards being worked for how to handle attachments with web services, but for now, these are your choices if you’re sticking to WSF out-of-the-box. When you deploy your SBO, both transfer mechanisms are automatically added to your service.

Base64 versus UCF

Base64 is the easiest to deal with but it may prove to be problematic for large attachments. The Base64 algorithm adds up to 33% to the size of the file and the encode/decode process can be expensive.

The WSF Development Guide has a .NET Base64 example but you should be able to get it working in Java with no problems. If you need help with the encode/decode step check out the dm-developer article referenced below.

UCF is a Java-based client application that is installed at run-time. It communicates with the WSF application server using servlets.

The WSF Development Guide provides a Java-based UCF example. Unfortunately, there are a few problems with it. First, there are some logic errors in the code. They aren’t major but you won’t be able to copy-and-paste, compile, and run without a couple of tweaks (the file name logic is bad, their web root doesn’t match the WSF default, and they use localhost which may or may not work in your case, depending on where you’ve installed the WSF).

Next, in order to initialize and work with the UCF you’ll need to make sure your classpath includes ucf-installer.jar which can be found in the root of the ws.war file.

The last issue is something I haven’t resolved yet. The sample UCF program calls a method that imports content followed by a method that exports content. For some reason the first call to the service works, but subsequent calls within the same program cause the program to hang. The problem occurs whether you are doing an import or an export and regardless of order. I’ve tried re-initializing the UCF and I’ve tried lengthening the session timeout but neither have worked. When you run an export or an import by itself, it works great. It’s when you try back-to-back UCF invocations that the hang occurs.

All services, all of the time?

If you wanted to use web services as the primary interface between other enterprise applications and the Documentum repository, you’d have to write your own SBO’s to provide even a basic set of “library services”–none are available out-of-the-box. That’s something Documentum ought to provide and they are promising to do so in a future release.

Of course you could always write your own web services layer that wouldn’t rely on SBO’s and would deal with attachments in whatever way worked best for your situation.

Getting started

  • Download and install the Web Services Framework from Documentum.
  • Read the WSF Development Guide.
  • Download and install Apache Axis to get a feel for the underlying framework.
  • If you are new to working with web services in Eclipse, work through this evaluation guide.
  • If you need help with the Base64 code/decode step, read the end of this article at dm-developer.