Documentum has two built-in object types, dm_relation and dm_relation_type, intended to be used together to create arbitrary relationships between objects. Documentum uses these two types internally to maintain some system-defined relationships, like annotations. These types are also useful for defining and creating your own types of relationships. For instance, in a particular project you might want to create a relationship between the project specification and the project design document. Then you could have a special check-in handler that sets a flag on the design doc (or emails the design team) when the specification changes. You could create the relationship by using a new dm_relation object to connect the two objects.
One important fact to consider before using dm_relations is that it is not possible to dump or replicate an object without including other objects related to it via dm_relations.
Every dm_relation object points to a dm_relation_type object that defines the nature of the relationship. You’ll want to create a dm_relation_type first and then create a dm_relation that points to that dm_relation_type and the two objects you want to relate.
Figure 1: Connecting a Relationship
The following is a description of the dm_relation_type object and how to use its attributes…
Use a CREATE OBJECT statement to create your dm_relation_type. See the “Syntax for Creating Relationships” section later in this article and the Documentum DQL Reference for CREATE OBJECT syntax.
Once you have created a dm_relation_type that describes the nature of the relationships you want to create, you are ready to create instances of dm_relaton that reference the new dm_relation_type. The following is a description of dm_relation and how to use its attributes:
The way dm_relations bind to versions of parent and child documents is defined in the permanent_link and child_label attributes. Permanent_link is FALSE by default. When set to TRUE it causes a new dm_relation to be created for each new version of the parent. In the example of a design document to specification relationship, you might want to set permanent_link = TRUE so that any new version of the specification (the parent) creates a new dm_relation that links it to the design document (child). You might also want to set the child_label = “CURRENT” so that the specification is always related to the current version of the design document (like in figure 3).
Figure 2: Binding rules when ‘permanent_link’ is False and ‘child_label’ attribute is used.
Figure 3: Binding rules when ‘permanent_link’ is True. Each version of the parent creates a new dm_relation.
You can use the CREATE OBJECT statement to create the DM_RELATION_TYPE and DM_RELATION objects necessary for a relationship. First, create the DM_RELATION_TYPE object that defines the type and behavior of the relationship. Then create a DM_RELATION object that references the DM_RELATION_TYPE object and connects two member objects. You can create many DM_RELATION objects that reference a single DM_RELATION_TYPE object.
This DQL example creates a type of relationship where a design document is the child of a specification document.
create dm_relation_type object set child_parent_label = 'has design dependency on', set parent_child_label = 'defines requirements for', set description = 'connects specifications to design documents' set parent_type = 'dm_document' set child_type = 'dm_document' set direction_kind = 0 set integrity_kind = 0 set relation_name = 'specification dependency', set security_type = 'SYSTEM'
This DQL example creates an instance of a ‘specification dependency’ relationship between two dm_documents.
create dm_relation object set parent_id = '090f4628800395cc', set child_id = '090f4628800395d9', set relation_name = 'specification dependency', set description = 'example of a specification dependency'
After you have created several relationships, how do you query to find all the related objects? First, you need to know how the binding rules are configured for the type of relationship you’re querying for…
Query to get all children if you know the parent id and there is NO permanent link:
Select child.object_name, child.r_object_id, child.r_object_id as object_id from dm_sysobject (All) child, dm_relation relation where child.r_object_id = relation.child_id and relation.parent_id= '[parent_object_id]' and relation.permanent_link=False
Query to get all children if you know the parent id and there is a permanent link:
Select object_name, r_object_id as object_id from dm_sysobject (All) where r_object_id in (select child_id from dm_relation where relation_name = 'specification dependency' and parent_id = '[parent_chronicle_id]' and permanent_link=True)
Query to get any children, whether or not the child label is filled in, getting the correct version if it is filled in or the specific object if it isn’t:
Select child.object_name, child.r_object_id as object_id from dm_sysobject (all) child, dm_relation relation where ((child.i_chronicle_id = relation.child_id and any child.r_version_label = relation.child_label) or (child.r_object_id = relation.child_id and relation.child_label is nullstring)) and relation.parent_id= '<parent_object_id>' and relation.permanent_link=True
Query to get the parent if you know the child and there is NO permanent link:
select parents.object_name, parents.r_object_id as object_id from dm_sysobject parents, dm_relation relation where parents.r_object_id = relation.parent_id and relation.child_id= '[child_object_id]' and relation.permanent_link=False
Query to get the parent if you know the child and there is a permanent link:
Select parents.object_name, parents.r_object_id as object_id from dm_sysobject parents, dm_relation relation where parents.i_chronicle_id = relation.parent_id and relation.child_id= '[child_object_id]' and relation.permanent_link=True
Can you create a relation between objects in different docbases?
No, you can’t create relationships to objects in another docbase using dm_relations. There is another relationship type called dm_reference that can relate objects in different docbases. However dm_reference is not intended to be used for creating user-defined relationships, but is used for system-defined relationships like links to remote objects and virtual documents with remote children.
What happens if I delete a document with a relation to another doc? Does the relation get deleted then or via dmclean?
The server will destroy the relationship object (dm_relation) immediately if either the parent or child is deleted. Dm_relation is a persistent type so it does not descend from dm_sysobject and therefore has no i_is_deleted flag. A dm_relation_type object will not be deleted when the last dm_relation referencing it is deleted.
This article is from Blue Fish.