Introduction

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.

The DM_RELATION_TYPE Type

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 (Click to Enlarge)

The following is a description of the dm_relation_type object and how to use
its attributes…

child_parent_label

A user-defined text string that names the child-to-parent aspect of this relationship. For instance, “has design dependency on” might be a good child_parent_label for the design document to specification relationship mentioned above. This value might be useful to query on when generating reports.

child_type

The type (or supertype) of objects that will be set as children in this type of relationship.

description

A string that is the general description of this relationship

direction_kind

The nature of the relationship between the related objects. These are valid (integer) values:

• 0 – parent to child
• 1 – child to parent
• 2 – objects are equal siblings

integrity_kind

Specifies the type of referential integrity used when deleting a related object. These are valid (integer) values:

• 0 – either member of the relationship can be deleted
• 1 – neither member can be deleted as long as the relationship exists
• 2 – if one member of the relationship gets deleted, so does the other

parent_child_label

A user-defined text string that names the parent-to-child aspect of this relationship. For instance, “defines requirements for” might be a good parent_child_label for the specification to design document relationship mentioned above. This value might be useful to query on when generating reports.

parent_type

The type (or supertype) of objects that will be set as parents in this type of relationship.

relation_name

A unique name for this type of relationship. Relationships that are system-defined begin with “dm_”. Don’t use “dm_” because you won’t ever be able to delete the dm_relation_type.

security type

The type of security used for dm_relation objects assigned to this dm_relation_type (by relation_name attribute). The valid (string) values are:

• SYSTEM – You must have Sysadmin or Superuser privileges to create, modify, or delete relationships associated to this dm_relation_type.
  Note: The exception to this is that it won’t prevent owners of objects in the relationship from deleting the objects. The
  side effect of deleting either object in a relationship is that the relationship itself will also be deleted. See the description
  of “integrity_kind” for more information on delete behavior.
• PARENT – The ACL for the relationship is inherited from the parent object in the relationship and RELATE permission will be required
  to create, modify, or drop the relationship. The exception to this is if the parent object is not a subtype of dm_sysobject, then no
  security will be enforced.
• CHILD – The ACL for the relationship is inherited from the child object in the relationship and RELATE permission will be required to
  create, modify, or drop the relationship. The exception to this is if the child object is not a subtype of dm_sysobject, then no
  security will be enforced.
• NONE – No security is applied to the dm_relation objects representing instances of this relationship. All users can create,
  modify or delete this kind of relationship.

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.

The DM_RELATION Type

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:

child_id

The r_object_id or i_chronicle_id of the child object in this relationship. If you use the i_chronicle_id, then you can use the “child_label” attribute to bind to a particular version.

child_label

(Optional) Version label of the version to bind to if an i_chronicle_id is specified in “child_id”

description

(Optional) User-defined description.

effective_date

(Optional) Not used by the system, a user-defined date. Custom logic could check this date to determine the state of the relationship.

expiration_date

(Optional) Not used by the system, a user-defined date. Custom logic could check this date to determine the state of the relationship.

order_no

(Optional) Not used by the system. Custom logic could use this integer value to order a set of relationships.

parent_id

The r_object_id or i_chronicle_id of the parent object in the relationship. Only use i_chronicle_id when you are also using permanent_link = “TRUE” to bind to the current version.

permanent_link

Set this to True and use the i_chronicle_id for the parent_id when you want every new version of the parent to be related to the child. A new dm_relation is automatically created for each new version of the parent (see figure 3). This setting is “FALSE” by default.

relation_name

Specifies a dm_relation_type object by name (relation_name attribute) that defines the type of relationship.

Binding Rules

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 documentfilename=”/article-assets/images/rel-diagram2.gif”b 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. (Click to Enlarge)

Figure 3:
Binding rules when ‘permanent_link’ is True. Each version of the parent creates a new dm_relation. (Click to Enlarge)

Syntax for Creating Relationships

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.

Creating a 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'

Creating a DM_RELATION Object

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'

Querying for Related Objects

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= '&ltparent_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

Frequently Asked Questions

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.