This response addresses questions about Document Relationship usage:
- Must an ODMA 2.0 DMS support Document Relationships?
- How can an application determine when a particular relationship is not supported?
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.
Contributors
Change History
It is not necessary for an ODMA 2.0 DMS to support Document Relationships.
The
ODMSTATUSresult codeODM_E_NOSUPPORTis possible for bothODMGetDocRelationandODMSetDocRelation.ODMA 2.0 operation
ODMQueryCapabilitycan be used to determine whether there is any support at all for each ofODMGetDocRelationandODMSetDocRelation. 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
ODMGetDocRelationallows 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.
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.
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.
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
lpszDocIdparameter. This ODMA Document ID also determines the DMS that will be employed to operate on the Document Relationship.The
pdwFlagsparameter specifies whether the relationship being operated with is to a child or a parent of the anchor document.
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
ODMSetDocRelationis 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.
On
ODMGetDocRelation, when Document Relationships are supported, a common response isODM_E_NORELATIONwhen an application requests information about a relationship that does not exist.ODMGetDocRelationis a straightforward operation: It reports what is there and fails when the requested relationship is not present.
ODMSetDocRelationis 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_FAILis the most likely response (to avoid implying thatODMSetDOcRelationis itself unsupported).ODM_E_ACCESScan occur when it is a matter of access rights rather than a limitation of the Document Relationship implementation.ODM_E_NOSUPPORTcan also be reported for an unsupported Document Relationship case. However,ODM_E_NOSUPPORTcan be mistaken for there being no Document Relationship support, rather than there being no support for an individual case.
Before using
ODMSetDocRelationon a particular document, first check for support of this function usingODMQueryCapability. If the function is supported, then accept anyODMSetDocRelationODM_E_NOSUPPORTresult value as an indication that the requested relationship is not supported. Likewise,ODM_E_FAILmay be an indication that the requested operation violates a requirement of the DMS.In performing
ODMGetDocRelationandODMSetDocRelationoperations, 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
ODMActivatemay 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
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 $