The Open Document Management API The ODMA draft standard attempts to define document-management functionality By Bill Rosenblatt

October  1995

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)

Mail this article to a friend

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?

In through the back door

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

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

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

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

Resources

• ODMA ftp repository
  ftp://ftp.capcon.net/pub/aiim/services/api
• Object Linking and Embedding
  http://www.microsoft.com/TechNet/technol/ole/prodfact/ole.htm
• OpenDoc
  http://www.austin.ibm.com/developer/objects/od1.html
• full-text search discussed in last month's column (September SunWorld Online)
  /sunworldonline/swol-09-1995/swol-09-cs.html
• A list of other Client/Server
  /sunworldonline/common/swol-backissues-columns.html#cs

If you have technical problems with this magazine, contact webmaster@sunworld.com

URL: http://www.sunworld.com/swol-10-1995/swol-10-cs.html
Last modified: