The Open Document Management API

The document metaphor is an extremely powerful and natural way of
integrating information and representing it to users.
But before it can become mainstream, vendors have to establish common
ground -- with databases and OSes as well as each other. ODMA is the
first step in that direction.
If you plan to develop applications that deal with documents as part
of an organization's core data, then you will need to pay attention.
(1,900 words)

In August's column, we talked about document
management and how it's likely to eclipse database management as the
required core software technology for many corporate client/server
systems. What does this mean for you as an application developer?
Specifically, how do you get your application to handle documents
instead of traditional files? The focus of this month's column is the
Open Document Management API (ODMA), a draft standard that attempts to
define document-management functionality in a standard way for
application developers. If you anticipate developing applications that
deal with documents as part of an organization's core data, then you
will need to know about ODMA.

As we explained a couple of months ago, the document metaphor is an
extremely powerful and natural way of integrating information and
representing it to users. Desktop technologies that support complex
document integration include the
Object Linking and Embedding
(OLE) standard in Microsoft Windows, the multi-platform
OpenDoc
standard, the World Wide Web's HyperText Markup Language (HTML),
and -- as a read-only rendering mechanism --
Adobe's Portable Document Format (PDF). These client-side compound-document
architectures cry out for the need to manage the data on the server
side. Complex data objects must be linked, embedded, cross-referenced,
searched, queried, distributed, and safeguarded -- as well as viewed,
edited, and printed.

Object data models fit into relational
databases like the proverbial square peg
into a round hole. How, then, to integrate?

The resulting requirements for document management, then, are
a confluence of existing server- and client-side technologies.
On the client side, those mentioned above; on the server side,
traditional database-management technology augmented with
content-based querying facilities --
such as full-text search that we discussed last month (September SunWorld Online).
Think about integrating something like Microsoft OLE with relational
database technology, and you might conjure up an image of a violent
frontal system rather than a marriage made in heaven. After all, OLE
purports to be an object model, and those of you who know data models
understand that objects fit in with relations like the proverbial
square pegs into round holes.

Yet vendors of client/server document management systems (DMS)
-- such as Documentum, Saros, and Interleaf,
all of whose products are based on relational database technology --
recognize the need to integrate desktop compound document
architectures with their systems. The question is, how? What exactly
do you integrate?

Advertisements

In through the back door

DMS vendors have started to answer that question collectively
by understanding three things:

They need to raise awareness of document management in general in
order to promote a viable industry. Document management is something
that directly benefits users, yet they're not likely to ask for a
document-management system as they would a spreadsheet, word processor,
or even a decision-support tool.

The right way to promote an industry is through open standards.

A subtle but important point: A DMS provides basic system services,
just as operating systems and database systems do. Therefore, as with
those kinds of systems, the right form for open DMS standards is an
API that fosters growth of the installed base through the intermediary
of application developers.

However, applications that make use of
document-management services must integrate with the DMS more tightly
than they would with the operating system
or DBMS, precisely because the objects that DMSes handle (documents)
are far more complex than those that OSes or DBMSes handle (files,
relational tables). Worse, DMS vendors want their products to
integrate with existing popular desktop applications that handle
documents. As a result, a standard API for DMS vendors must not only
provide entry to DMS services, it must do so in a way that makes it
easy for application developers (or maintainers) to work with.

A subtle but important point:
A DMS provides basic system services,
just as operating systems and database systems do.

With these points in mind, a number of vendors -- including makers of
databases and desktop operating systems (yes, including Microsoft)
as well as DMSes -- attempted to define a
standard API for document-management systems. Version 1.0 of the Open
Document Management API was published in June 1995. Its intent is as
follows:

To make DMS services available to users of desktop applications
in a seamless manner so that these services appear to the user
like extensions of the applications.

To reduce the application vendors' burden of having to deal with
multiple DMS vendors. By writing to ODMA, an application vendor has
potentially integrated its application with all supporting DMSes.

To reduce the DMS vendors' burden of integrating with multiple
applications. By supporting ODMA, a DMS vendor has potentially
integrated with all applications that have written to ODMA.

To reduce effort and complexity needed to install and maintain
DMSes.

File fixations

The DMS vendors' main hurdle in getting application developers to
interface their products to document-management systems is to overcome
their dependence on files as the primary units of
information. A DMS deals in documents, which may map (loosely) to
files on today's desktop platforms, but the DMS need not store them as
such. For example, it could store documents as BLOBs in a relational
database, or as objects in an object database. DMS vendors use
document IDs to refer to documents; these resemble object IDs
in object-oriented systems.

Therefore, the central challenge of integrating document management
with desktop applications is to get those applications to handle
document IDs as well as pointers to files. For example, a word
processor should be able to get a document from a DMS through its
document ID and read it in for editing, just as if the document were a
file on the desktop computer's local hard drive. Similarly, the word
processor should be able to save a newly-created document -- or a
previously existing file -- in the DMS instead of on the hard drive.

The ODMA addresses this issue by targeting the File menu on
applications that deal with documents as its integration point. At a
cursory glance, in fact, the API looks like nothing more than a
call-level replica of commands on a File menu: it contains
functions like Open (ODMOpenDoc), New (ODMNewDoc), Save, SaveAs, and
Close.

The ODMOpenDoc function tells the DMS to retrieve a document, copy it
to a temporary local file, and open that file for editing or viewing.
In effect, this lets applications deal with DMS documents as if they
were standard files, thus minimizing the amount of work that
developers must do to ODMA-ize their apps. This scheme is fine for
simple documents -- those of a single format. But it creates
complications when dealing with complex documents.

The central challenge of integrating
document management with desktop applications
is to get those applications to handle
document IDs as well as pointers to files.

For example, consider a Microsoft Word file with an embedded table
that's actually an Excel spreadsheet object and a picture that's
really a graphics object created with ShapeWare's Visio program. On
the client PC, this is represented as a Word file with OLE links to
the Excel and Visio files. But the DMS server need not represent these
links with OLE -- in fact, if it's a multi-platform DMS, it shouldn't
do so. If the DMS contains an object database, it could naturally
represent the complex document as a hierarchy of database objects. The
Documentum DMS, on the other hand, uses a relational database and has
its own virtual document scheme for defining complex
documents. The DMS must be able to re-create the complex document as
an OLE-linked hierarchy when it's on Windows platforms -- or as a
Publish and Subscribe document on a Macintosh. Such conversions can be
hellish to implement, but they are necessary for handling today's
increasingly complex documents.

Cracking 8-dot-3

Thus far, the DMS functionality I have described is little more
than that of a file server. The true power of client/server document
management is in the many ways a DMS user can categorize and retrieve
documents. Documents can have data attributes (such as the name of the
author, date of publication, and revision number) that can be queried,
and the DMS can index documents for full-text retrieval, as we saw in
last month's column.
ODMA gives application developers access to all that power through the
function ODMSelectDoc. ODMSelectDoc tells the DMS to pop up a "find
document" window, let users select a document, and return the ID of
that document to the calling application. This "find document" window
can be anything -- a data query form, a full-text search interface, a
natural-language query facility, or any combination of these. This is
obviously much more interesting than a dialog box that prompts the
user for a simple filename.

Various problems arise when integrating asynchronous DMS
functionality with desktop applications. By asynchronous, I mean
things that the DMS server can do in the background without
interacting with the desktop application or user. One example of such
a task is updating a DMS full-text index to include documents that
have been newly checked into the DMS. Another could be version
control, such as comparing a newly saved document with a previous
version and annotating differences. In the ODMA spec, the function
ODMActivate lets a client application call some predetermined function
on the DMS server, which would start this type of asynchronous
process.

ODMA does what it was intended to do:
jump-start a market for DMS by making it
as easy as possible for the systems to work
with today's file-oriented applications.

ODMA does what it was intended to do: jump-start a market for DMS by
making it as easy as possible for the systems to work with today's
file-oriented applications. The problem with ODMA is it embodies too
deeply the assumption that client applications deal with traditional
files -- rather than the generalized persistent objects that the next
generation of desktop operating system will be based on. It will be
much easier to integrate document-management services with
object-based applications, since object hierarchies are better ways to
model complex documents than are traditional files. But in the
meantime, ODMA gives application developers a straightforward way to
take advantage of the power of client/server document management.

Bill Rosenblatt is director of Publishing Systems in the New York
City office of the Times Mirror Co. He can be reached at
bill.rosenblatt@sunworld.com.