Introducing Virtual Documents
Virtual documents are a way to combine documents whose contents have a variety of formats into one document.
You can associate a particular version of a component with the virtual document or you can associate the component’s entire version tree with the virtual document. Binding the entire version tree to the virtual document allows you to select which version is included at the time you assemble the document.
Users create virtual documents using the Virtual Document Manager, a graphical user interface that allows them to build and modify virtual documents. However, if you want to write an application that creates or modifies a virtual
document with no user interaction, you must use the API.
Although the components of a virtual document can be any SysObject or SysObject subtype except folders, cabinets, or subtypes of folders or cabinets, the components are often simple documents or another virtual document.
Documentum imposes no limits on the depth of nesting in a virtual document.
Content Server does not allow you to remove an object from the Docbase if
the object belongs to a virtual document. This ensures that the referential integrity of virtual documents is maintained.
Virtual Document Architecture
Content Server uses two object types to store information about virtual documents:
• Containment object type (Internal name: dmr_containment)
• Assembly object type ( dm_assembly)
Containment objects contain information about the components of a virtual document. Each time you add a component to a virtual document, a containment object is created for that component. Containment objects store the information that links a component to a virtual document. For components that are themselves virtual documents, the objects also store information that the server uses when assembling the containing document. The connection between the parent and the components is defined in two attributes of containment objects: a_contain_type and a_contain_desc.
The process of selecting individual components to produce a virtual
document is called assembling a virtual document. Assembly objects make up assemblies. An assembly is a snapshot of a virtual document at a particular time. An assembly records the exact components of the virtual document at the time the assembly was created. Each assembly object in an assembly represents one component of the virtual document.
Conditional Assembly:
Assembling a virtual document selects a set of the document’s components for
publication or some other operation, such as viewing or copying. When assembling a virtual document, you can identify which components to include. You can include all the components or only some of them.
Early and Late Binding:
Attaching a specific version of a component to a virtual document is referred to as binding. Early binding occurs if you bind a specific version of a component to a document when you add the component to the document. Late binding occurs if you bind a specific version of a component to a document when you assemble the document.
Freeze
Freeze methods allow you to freeze a virtual document and an assembly associated with that document. When you issue a Freeze method against a virtual document, if there is an assembly associated with that document, you have the option to freeze the assembly also. Users cannot modify the content or attributes of a frozen virtual document or the frozen assembly components. Nor can they add or remove assembly components. However, users are allowed to modify any components of the virtual document that are not part of the frozen assembly. Although users cannot remove those components from the document, they can change the component’s content files or attributes.
Freezing sets the following attributes of the document to TRUE:
• r_immutable_flag
This attribute indicates that the document is unchangeable.
• r_frozen_flag
This attribute indicates that the r_immutable_flag was set by a Freeze method
(instead of a Checkin method).
There are two attributes in containment objects that control how components that are themselves virtual documents behave when the components are selected for an assembly. The attributes are use_node_ver_label and follow_assembly.
·Persistent object Attribute:
r_object_id: The r_object_id attribute contains the object's identifier, its object ID. This number is
generated by the server when the object is created and is unique.
·SysObject Attributes:
r_is_virtual_doc: If the attribute is set to TRUE, the client applications always open the document in the Virtual Document Manager.
r_link_cnt: records how many direct components belong to the virtual document. Each time you add a component to a document, the value of this attribute is incremented by 1.
i_chronicle_id :Object ID of the root object of the version tree that contains this object.
·Containment Type Attributes
component_id: Chronicle ID of the component.(The chronicle ID is the objectID of the original version of an object. If the object has no versions, then its object ID and chronicle ID are the same.)
parent_id: Object ID of the object that directly contains the component.
·Assembly Type Attributes
book_id :Object ID of the topmost containing document in the virtual document structure that contains the component described by this assembly object.
component _chron_id :Chronicle ID of the component represented by the assembly object.
component_id: Object ID of the component of the virtual document
The main attribute of a document that has to do with virtual documents is r_link_cnt. This attribute contains the number of children that are linked to a virtual document. If r_link_cnt=0, the object is not a virtual document. If r_link_cnt is > 0 the object is a virtual document. Note that r_link_cnt will never have a value of 1, because the parent of the virtual document is also considered a child. So if you add one component, r_link_cnt=2. If you add a second component, r_link_cnt=3, and so on.
Also note that this same attribute applies to dm_folder, indicating how many objects are linked into the folder.
There is no attribute of a document to show that it is a component of a virtual document.
Object Types
Documentum uses a special object to keep track of all the virtual documents in the docbase. It is called dmr_containment, and it has 4 attributes: parent_id, component_id, order_no, and version_label.
The dmr-containment object contains pointers to the virtual document and its components.
Note that the parent_id is the r_object_id of a specific version of the parent. This means that the components and the order of the components can change from one version of the parent to the next.
The component_id attribute is actually the i_chronicle_id of the component. This makes sense because the i_chronicle_id represents the entire version tree of an object, and we don't know what version of the various components we want until we issue the query to gather the components up (for more on this, see Late Binding vs. Early Binding).