ODMA: Open Document Management API

FAQ Q990401

Creating ODMA Document IDs



0.51 2010-08-30 -11:18 -0700

This information is also part of ODMA 2.0 Library Files edition 2.0-1.  For later editions and current status, consult the ODMA 2.0 Library Files description page.


This response addresses questions about the freedom that a DMS integration has to produce ODMA Document IDs that fit with its purposes.

There is information on achieving maximum interoperability and international acceptability in the way ODMA Document IDs are formatted.

1. Required Document ID Format

2. Document ID Usage

3. Interoperability Considerations


Change History


ODMA depends on ODMA Document IDs for locating the correct DMS integrations to use in performing individual operations on managed documents.  In the ODMA specification,  most operations require a Document ID as a parameter.

It is necessary for a DMS Integration to provide and then to accept those ODMA Document IDs of its creation.  

ODMA middleware will reject a Document ID that does not identify an available DMS.  A DMS must reject all ODMA requests having Document IDs that are invalid for that DMS.

ODMA dictates the format for that part of the ODMA Document ID that is used by ODMA middleware for selecting a DMS.  The remainder of the Document ID is determined by the DMS.  

The only constraints on the DMS-determined portion of the ODMA Document ID are ones on the characters used and on the overall size of the Document ID.  The specific method for distinguishing individual documents under control of an ODMA DMS is completely determined by the DMS implementation.

This FAQtip presents the basic requirements and additional considerations for creating and using ODMA Document IDs.

1. Required Document ID Format

see also: 
ODMA 2.0 Specification, Section 1.1, Document IDs
ODMA Version 2.0 Errata on Section 1.1, Document IDs
X010100: Inappropriate Messages to Users
X000802: ODMA Connection Manager Passes Malformed Document IDs
X000805: Connection Manager does not adjust to code-page in use
Connection Manager depends on non-Standard string function stricmp

ODMA has simple requirements for Document IDs:

  1. A Document ID must be a text string in the local single-byte character set.
  2. It must take no more than ODM_DOCID_MAX units of char storage, including the terminating '\0' character.
  3. It must be used in a case-insensitive way and should be formatted so that it can be provided on a command line or embedded in text (e.g., in e-mail) without problem.
  4. The first part of the ODMA Document ID must satisfy a simple fixed format:


  5. where dms-id is at least 1 and at most (ODM_DMSID_MAX-1) characters.  
  6. There should be no spaces or punctuation in the dms-id portion.  Non-printable characters are never permitted.  For maximum international interoperability, employ only the Roman letters A to Z and the decimal digits 0 to 9 in the dms-id.

The dms-id is used by ODMA middleware to determine the correct DMS integration to use for operating with the identified document.  

Current ODMA middleware depends on the leading part of the ODMA Document ID being in the ISO 646 (ANSI) 7-bit character encoding.  Use of characters having additional, 8-bit character codes may lead to confusion in interchange of the Document IDs, especially between platforms having different default character-set encodings.  Proper case-insensitive interpretation of the dms-id by middleware is assured only when these limitations have been honored.

2. Document ID Usage

Applications are required to treat ODMA Document IDs as "opaque," having no predictable structure.  Applications that retain Document IDs longer than the current session must take precautions to ensure that the information is recorded in a way that preserves its fidelity to the original if ever resubmitted as a parameter to a future ODMA operation.  This includes making sure that any dependencies on a particular character-set encoding (e.g., a particular code page) are captured in a way that conversion for a system with a different character-set encoding preserves the characters of the ODMA Document ID.  (Any code page or character-set encoding that incorporates the ASCII character set has this quality, so long as DMS integrations are designed to employ only those characters in ODMA Document IDs.)

ODMA middleware does not examine that part of an ODMA Document ID that follows the ::ODMA\dms-id\ portion of any Document ID not manufactured by the middleware itself (i.e., for ODMA 1.5 query results).  

So long as the length, character-set and character-code requirements of ODMA are satisfied, the remainder of the Document ID can be encoded in any way that allows the DMS integration to locate the identified document in the future. 

When a DMS integration is atop a document-management system having its own identification scheme, the common approach is to recode such identifications, with sufficient supplemental data so that the original identification can be recovered by inspection of the ODMA Document ID. The supplemental information may include identification of the specific repository that was used, so that identifications applicable to one repository will not be mistaken for similarly-identified documents of other repositories supported by the same DMS integration.

How this is done is dependent on the implementation of the DMS Integration.

For example, the following ODMA Document ID applies for a fictitious DMS Integration, 


where there is a globally-unique and privately-generated identifier for the DM-FOO-integrated repository, and then a unique within-repository document identification following the "#"-separator.

There is a special case that each DMS integration must support: The ODMNewDoc function returns a place-holder that is used temporarily until an ODMSaveAs or ODMSaveAsEx operation is performed to establish the official ODMA Document ID for a new document.  Each DMS has its own implementation of this scheme.  For example,


might constitute a placeholder for a reservation issued for a pending document that the DMS is waiting for the application to define further.  

Some DMS integrations use even simpler schemes than this, having a specific, constant ODMA Document ID that is used for all pending new documents of that DMS.   The DMS doesn't generate an original ODMA Document ID until the application performs an ODMSaveAs or ODMSaveAsEx for the first time on the new document.

There are many other variations.  Here are some ODMA Document IDs produced by some DMS integrations:


3. Interoperability Considerations

Job Jar:

  1. Find more-precise reference for ISO 646 and related specifications.
  2. Remember to mention the problem of different lengths between Win16 and Win32.
  3. Locate the discussion about provision on command lines.
  4. Provide guidance about registering DMS IDs.  
  5. Look at clearly differentiating between application usage and DMS usage.

For ODMA DMS integrations to interoperate successfully across multiple computers, the dms-id should be unique among all known DMS integrations.  In this way, an ODMA Document ID is never supplied to a DMS integration for which it is not intended.

It is also strongly recommended that the ODMA Document ID be globally unique.  ODMA Document IDs may be stored in files, carried in documents as links to other documents, and transmitted to others using e-mail and other transfer techniques.  A Document ID may be used much later than when it is first delivered in a response to an ODMA operation.  Globally-unique ODMA Document IDs allow a DMS integration to determine whether it actually has access to the repository to which the Document ID applies, or not.


Balaz Branislav (2000-10-13)
asked questions about the requirement for and variability of ODMA Document IDs and what are the requirements
Dal Ghotra (1999-04-12)
raised the original questions concerning what one can do with the DMS-specified part of an ODMA Document ID.
Dennis Hamilton (2000-10-20)
collected the contributed material and drafted the response used for this FAQtip.

Change History

0.51 2005-02-03-16:23 Transfer from Q000014 to 1999/Q990401
As part of the 2005 ODMA refresh, move to a convenient place, upgrade page style, and add a job jar and diary.  Perform light editing of wordings.
0.50 2001-02-12 Add Document ID example, correcting punctuation.  
Expand section on interoperability considerations.
0.35 2000-11-29 Expand on practices and use of DMS ID.
0.25 2000-11-13 Initial complete statement for review
0.10 2000-10-16 Place-holder and outline for a note to be reviewed and developed further.  

Hard Hat Area (Construction Zone) You are navigating the
ODMA Interoperability Exchange.

created 2000-10-16-13:01 -0700 (pdt) by orcmid
$$Author: Orcmid $
$$Date: 10-08-30 11:19 $
$$Revision: 38 $