AIIM DMware ODMA FAQ Q001000

DocRelation Usage

 Version 0.10 Last updated 2000-10-18-22:26 -0700 (pdt)
The latest version of this information is available on the AIIM DMware ODMA site.

This response addresses questions about Document Relationship usage:

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

This document is designed to be used in the same file location as HTML edition 2.0-3 of the ODMA 2.0 Specification and the Errata for that edition.  Shortcuts in this document depend on proximity to a copy of the specification.  A convenient way to make sure all necessary materials are present is to download the complete ODMA 2.0 Documentation Files package.

1. Required DocRelation Support

2. Document Relationship Operations

3. Recommended Practices


Change History

1. Required DocRelation Support

It is not necessary for an ODMA 2.0 DMS to support Document Relationships.  

The ODMSTATUS result code ODM_E_NOSUPPORT is possible for both ODMGetDocRelation and ODMSetDocRelation

ODMA 2.0 operation ODMQueryCapability can be used to determine whether there is any support at all for each of ODMGetDocRelation and ODMSetDocRelation.  It is valuable to establish this prior to using those operations on a given document.

When an ODMA DMS integration provides for relationships among documents, the relationships can be traced using the ODMA 2.0 API.  Operation ODMGetDocRelation allows parent-child relationships to be enumerated and navigated.

The ODMA 2.0 API does not control what documents may be in relationships to others, nor all of the constraints that might apply to the relationships.  It is presumed that additional configuration of the DMS integration and of the repository operate behind the scenes of the ODMA 2.0 API.  Control of relationship support, if available, is presumably through the DMS user interface.

Operation ODMSetDocRelation, if supported, allows parent-child relationships to be created, updated, and deleted.  Again, the success of the operation will depend upon constraints and policies of the DMS integration and the underlying repositories.

The ODMA Document Relationship operations are effectively stateless.  That is, a document need not be opened when its relationships are navigated or manipulated.  Likewise there is no implication that the check-out status of a document has any impact on the ability to perform Document Relationship operations.

2. Document Relationship Operations

see also: ODMA 2.0 Specification Errata on DocRelation Usage

The ODMA 2.0 Document Relationship model provides the possibility of any document (rendition) being a child or a parent. The specific relations provided will depend on the implementation made available via the DMS integration.

2.1 ODMA 2.0 Document Relationship Model

In the ODMA 2.0 model, there is the possibility of any document being a child in more than one way, as well as being a parent in more than one way. It is even possible to realize different orderings of how the child sees all of its parent and how a parent sees all of its children in the navigation of a set of Document Relations. 

The degree to which a given DMS integration supports these cases will depend on the implementation and can generally be discovered only by trial-and-error or independent knowledge of the DMS integration's model for document relationships.

2.1.1 Documents Relate as Parents and as Children

Document Relationship operations are always performed using the ODMA Document ID of a particular document as the anchor for the operation.  This will be specified by the lpszDocId parameter.  This ODMA Document ID also determines the DMS that will be employed to operate on the Document Relationship.

The pdwFlags parameter specifies whether the relationship being operated with is to a child or a parent of the anchor document.

2.1.2 Parent-Child Document Relationships are Unique

In the ODMA 2.0 Document Relationship model, a document cannot be a child of the same document more than once, and (consequently) cannot be the parent of the same document more than once.  

That's because there is no way to specify when a different relationship with the same parent and child is intended: the relationships are uniquely identifiable only by the ODMA Document ID of the parent and of the child.

The ability to control ordering in the list is not useful as a way to introduce multiple relationships between the same pair of parent and child documents.  Ordering is not required to be supported, in which case there is no way to introduce a relationship that differs only by position.  When relationship ordering is supported, the placement must be unambiguous, making duplicate siblings in the same list of children (or parents) unworkable.  

Because ODMSetDocRelation is also used to change and delete an existing relationship, there are not enough parameters and flags to unambiguously operate if more than one parent-to-child document relationship can exist between the same parent and child document.

2.2 ODMGetDocRelation Considerations

On ODMGetDocRelation, when Document Relationships are supported, a common response is ODM_E_NORELATION when an application requests information about a relationship that does not exist.  ODMGetDocRelation is a straightforward operation: It reports what is there and fails when the requested relationship is not present.

2.3 ODMSetDocRelation Considerations

ODMSetDocRelation is used to establish and to alter Document Relationships that a given document participates in.  In these cases, it is possible to request a Document Relationship, or change to an existing Document Relationship, that the DMS integration does not support.  When the requested relationship is not supported, ODM_E_FAIL is the most likely response (to avoid implying that ODMSetDOcRelation is itself unsupported). ODM_E_ACCESS can occur when it is a matter of access rights rather than a limitation of the Document Relationship implementation.  ODM_E_NOSUPPORT can also be reported for an unsupported Document Relationship case.  However, ODM_E_NOSUPPORT can be mistaken for there being no Document Relationship support, rather than there being no support for an individual case.

3. Recommended Practice

Before using ODMSetDocRelation on a particular document, first check for support of this function using ODMQueryCapability.  If the function is supported, then accept any ODMSetDocRelation ODM_E_NOSUPPORT result value as an indication that the requested relationship is not supported.  Likewise, ODM_E_FAIL may be an indication that the requested operation violates a requirement of the DMS.

In performing ODMGetDocRelation and ODMSetDocRelation operations, it is possible for unexpected and surprising situations to arise as the result of different users or applications operating against the same ODMA documents.  Designs for ODMA-aware applications should anticipate that there is no assurance of stability of a document's relationships between one ODMA Document Relationship operation and another.

Finally, it is important to realize that the different documents involved in an ODMA Document Relationship need not be sensible to the same ODMA-aware applications.  For example, the same application may not be capable of processing or editing both the parent and the child documents in an ODMA Document Relationship.  In principle, it is not even required that the parent and child documents be supported by the same ODMA DMS integration.  Creative use of ODMActivate may be required to support an user in navigating to and using documents that are paired in ODMA Document Relationships.


Dennis Hamilton
researched the question and organized versions 0.10 for initial trial and review.
V.J. Mohan
noticed that DocRelation seemed underspecified and requested clarification

Change History

version 0.10 Minimalist information providing a sketch to be reviewed and developed further.  

created 2000-10-17-13:11 -0700 (pdt) by orcmid
$$Author: Orcmid $
$$Date: 00-10-20 10:01 $
$$Revision: 4 $