Posts Tagged ‘DQL’

kVisia: Product Overview

March 18, 2015 Comments off

Howdy Users and Buddies,

Today I want to share on kVisia, a product that provides the core functionality to automate, control and deliver an organization’s engineering and enterprise business processes to the desktop or Web. It holds the business rules, executes the XML configurations, builds the business forms, and implements the lifecycles that automate an organization’s business processes.

I think the only Prerequisites that you need to know is , Basic concept of client-server applications and Documentum Architecture.

Let me put it in Content Wise for better understanding with a bit of background of what’s there , what’s missing and how this can be achieved.

  1. Abstract

Today the current era is defined by the terms like data, information, knowledge, wisdom etc. and in this electronic world the difficulty to manage data in abundance has begotten many technologies and one of them is the Documentum.

Documentum is nothing other than a Content Management Tool but its vastness and its ability to cater to almost all sorts of data types available are so rich in itself that these days it is widely used. If we undo the Documentum technically then it gives an edge over the Relational Database Management System by not storing only the Meta data but also storing the content in its native format.

kVisia blends with Documentum to bolster the level and depth of automation which can be achieved by the Documentum alone and this is what this document discusses in detail.

  1. Introduction

kVisia comes of McLaren Software Limited and users need to have a license before using it. McLaren is ISO 9001 certified and it has been accredited Independent Software Vendor for Documentum and FileNet. It has got 360+ customers worldwide and it operates from UK, USA and Switzerland.

In fact kVisia is an Enterprise Engineer product that encapsulates best practices and domain expertise. This is a user configurable application consisting of XML files managed by repository and standardized on a single ECM platform. It is also believed to be powered by Documentum.

For better understanding of the kVisia we can go through the following questions and answers that will help one to identify the need.

How does it help me?

Very quickly configure the user interface and deliver it to the Desktop and Web users.

Is it easy to change?

Very easy, configuration files are stored in the Docbase in XML format.

Configurable interface using objects and tables.

Do the configuration files allow me to control inputs?

Very complex business rules can be enforced via the XML files.

Validations at creation, promotion and check in.

  1. kVisia suite

kVisia suite consists of following three components:

  1. McLaren Studio
  2. McLaren_Core DocApp
  3. McLaren_Foundation DocApp

3.1 McLaren Studio

McLaren Studio provides a user-friendly desktop application that allows users to create and edit XML configuration files that will conform to the rules of the Document Type Definition (DTD).

An XML (eXtensible Markup Language) configuration file is a structured file consisting of many elements. Elements are ordered into a tree structure or hierarchy. Elements may have parent or child elements, and may also contain attributes. An element without a parent element is the highest in a tree structure and is called a root element. Not all of the elements will have child elements.

The structure of a valid XML file is defined in a DTD (Document Type Definition) file. The DTD contains the rules that apply to each XML configuration file; these include the definitions of parent and child elements, element attributes, and how each element can be used

The appearance and behaviour of user dialogs can be modified without the need to change programme code simply by changing settings in the appropriate XML configuration file. A definition of the appearance and behaviour of a dialog is referred to as a “configuration”. A common need, however, is to display different configurations under different circumstances. For example, members of different groups may need to fill in different properties on documents, and the document’s properties may change as it moves from state to state in a lifecycle. The definition of such a scenario is referred to as a “mapping”. When you do not want to differentiate functionality between different groups, lifecycles and states, there is a value called {default} that will apply to all circumstances.

The Actions for which dialogs can be defined using an XML configuration file are:


When the user issues the New command, a customized dialog can be displayed. Commonly deployed features include automatic document numbering, interactive project allocation and any additional attributes (optional or mandatory), which may be required to be stored for the document.


A customized Properties dialog can be displayed. Fields can be made editable or read-only as required.


When the user performs an import, a customized dialog can be displayed which may typically employ features similar to those used in the New dialog.


When the user performs a copy and paste action, a customized dialog can be displayed which may typically employ features similar to those used in the New dialog.


For each document type, a search dialog referred to as QuickFind can be defined and viewed by the user in the Docbase through the McLaren menu. The attributes that can be searched on are configurable and search options such as Between, Greater Than, Containing, etc., can be specified.

 3.2 McLaren_Core DocApp

Having installed kVisia you get two sets of Docapps in the Docbase, one is the McLaren_core and the other one is McLaren_foundation. The McLaren_core Docapp is available to the user of a Documentum repository. It is always suggested that one should have the overview of the additional functionality as a result of the deployment of the kVisia before configuring the product to suit the business need.

As the name suggests McLaren_core Docapp provides the basic functionality like New, Import, Properties, Copy, QuickSearch etc to be configured. As discussed above, we use the XML configuration tool McLaren Studio to configure it.

For each Object Type used in the repository, an XML Configuration File can be created and configured to define the appearance and behavior of the various dialogs for documents of that Object Type. The definition of the appearance and behavior of a dialog is referred to as a configuration, and different configurations can be displayed in different circumstances.

3.3 McLaren_Foundation DocApp

The McLaren_foundation installation enables you to deploy a pre-configured implementation of the Core technology which transforms it into a user application specifically adapted to the engineering environment, providing a ready-for-use engineering repository. It deals with the following configurations:

User Roles that is associated with Menu Systems and User Dialogs that are adapted to those roles.

Object Types for documents and folders.

XML Configuration Files that define the content, appearance and behavior of the New, Copy, Properties, Import and QuickFind dialogs for the supplied Object Types in accordance with the current user’s User Role and the document’s lifecycle and state, including pre-configured, automatically generated document numbering.

Check in dialogs which are specifically adapted for each supplied type of engineering document.

Automated document revision numbering that reflects common design practice. Revision numbers start at 0 and the first issued version is 1, the second 2, the third 3, etc. When a document is checked in for the first time, a numeric value is assigned and incremented each time it is checked in.

  1. Traditional – VB (Desktop) Vs kVisia(Desktop & Web)

Following Comparison lets you know how much flexibility kVisia provides and how much time and effort it saves.

Traditional – VB (Desktop) kVisia (Desktop and Web)
Ø  Obtain VB source code.

Ø  Open VBP.

Ø  Edit GUI.

Ø  Add code to populate list.

Ø  Add validation rules.

Ø  Save source code.

Ø  Compile DLL.

Ø  Create CAB file.

Ø  Open DocApp in Composer

Ø  Edit the component ACX and

replace CAB file.

Ø  Check DocApp back in.

Ø  Not available until next user login.

Ø  Check out XML.

Ø  Edit XML kVisia Studio.

Ø  Add XML tag.

Ø  Specify properties.

Ø  Save and Check back in.

Ø  Change available immediately (no logout required).

  1. Benefits
  • Easy to manage development process as applications are configured via XML using Studio
  • Fast route from innovation to user acceptance
  • Shorter time from design through to development
  • Shorter time to deploy to the business users
  • Reduces development costs
  • Future upgrades are minimised
  • Simple deployment and at a local level of control
  • Speeds up implementation process through rapid configuration

Hope you like the post, Feel free to post your comments and I will reply back to any queries that you have.

Adios , Have a great day ahead…

Relationship and Virtual Documents in Documentum

November 26, 2011 Comments off

This Post explains how the concept of relationships and virtual documents can be used to relate objects in Documentum using Documentum Foundation Classes (DFC).


  1. Relationship: A relationship implies a connection between two objects. When an object is related to another object then we can define which object is the parent object or the child object or if they are equal. Relationships are system-defined as well as user-defined. In the BOK, we confine our self to user-defined relationships.
  2. Virtual Document: In Documentum, a document which holds other documents i.e. a document which acts as a container is called as a virtual document. A virtual document can contain other virtual documents. The document which acts as a container is called the parent document while the documents which are contained in parent document are called as child documents.

Overview on relationship:

Two built-in object types dm_relation and dm_relation_type are to be used to create relations between any two objects. The dm_relation_type object defines the behavior of the relation. The dm_relation object identifies the dm_relation_type object and the two objects between which the relation needs to be created. Pictorially it can be shown as:


The dm_relation_type object has following attributes:

  1. child_parent_label: It defines the child to parent feature of the relation.
  2. parent_child_label: It defines the parent to child feature of the relation.
  3. description: It gives the general description of the relation.
  4. parent_type: It defines the type of objects that will act as parents.
  5. child_type: It defines the type of objects that will act as child.
  6. direction_kind: It defines the nature of relationships between the objects. The expected values are:

a)    1 – Parent to Child

b)    2 – Child to Parent

c)    3 – Objects are at equal level

7. integrity_kind: It specifies the type of referential integrity used when either of the two related objects has to be deleted. The expected values are:

a)    0 – Any of the two related objects can be deleted.

b)    1 – As long as the relation exists, neither of the related objects can be deleted.

c)    2 – If one of the related objects gets deleted, other one also gets deleted.

      1. relation_name: Specifies a name for the relation
      2. security_type: It indicates the type of security to be used for the relation object. The valid values are:

a)    SYSTEM: If this value is used, then super-user privileges are required for creating, deleting or modifying the relationships pertaining to this dm_relation_type object.

b)    PARENT: In this case, the ACL for the relation is inherited from the parent object in the relation and RELATE permission is required to create, modify, or drop the relation. The exception to this is if the parent object is not a subtype of dm_sysobject, then no security will be enforced.

c)    CHILD: In this case, the ACL for the relation is inherited from the child object in the relation and RELATE permission is required to create, modify, or drop the relation. The exception to this is if the child object is not a subtype of dm_sysobject, then no security will be enforced.

d)    NONE – In this case, no security is applied. All users can create, modify or delete this kind of relationship.

The dm_relation object has following attributes:

  1. child_id: It is the r_object_id or i_chronicle_id of the child object in this relation. If i_chronicle_id is used, then ‘child label’ attribute can be used to bind the parent object to a particular version of child.
  2. parent_id: The r_object_id or i_chronicle_id of the parent object in the relations. If the attribute ‘permanent_link’ is set to TRUE then only use the i_chronicle_id of the object.
  3. permanent_link: If every new version of the parent object has to be related with the child object, then the value for this attribute must be set to TRUE and i_chronicle_id should be used in the parent_id attribute. By default the value is FALSE.
  4. relation_name: It specifies the value of relation_name attribute of the dm_relation_type object that defines the type of relationship.
  5. child_label <Optional>: If i_chronicle_id is used in the attribute ‘child_id’, then the label of the version of the child object is to be specified here.
  6. description <Optional>: Specifies the description.
  7. 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.
  8. 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.
  9. order_no<Optional>: Not used by the system. Custom logic could use this integer value to order a set of relationships.
  • Creation of dm_relation_type object using DQL: The query used to create a dm_relation_type object is as follows:

create dm_relation_type object

set child_parent_label = ‘<Child to parent label>’,

set parent_child_label = ‘<Parent to child label>’,

set description = ‘<Description>’,

set parent_type = ‘<Document type>’,

set child_type = ‘<Document type>’,

set direction_kind = <0 or 1 or 2>,

set integrity_kind = <0 or 1 or 2>,

set relation_name = ‘<Name of Relation>’,

set security_type = ‘<SYSTEM or PARENT or CHILD or NONE>’

  • Creation of dm_relation object using DFC: Following methods which returns an object of type dm_relation can be used to create a dm_relation object.

1. addChildRelative(relationTypeName, childId, childLabel, isPermanent, description): This method has to be invoked on the object which is going to act as Parent in the relation. The parameters it takes are

a)    relationTypeName – Name of a valid dm_relation_type object.

b)    childId – The r_object_id or i_chronicle_id of the child object of the relation.

c)    childLabel – Version label of the child object. If this is ‘null’, the relation will contain no child label.

d)    isPermanent – Specifies if the link permanent. Valid values are TRUE or FALSE

e)    description – Specifies the description for the relation object. If ‘null’, the relation object will not have a description.

2.addParentRelative(relationTypeName, parentId, childLabel, isPermanent, description): This method has to be invoked on the object which is going to act as Child in the relation. It takes the same parameters as the method addChildRelative takes except instead of r_object_id or i_chronicle_id of the child object we pass the r_object_id or i_chronicle_id of the parent object as the parameter parentId.

Note: dm_relation object can be created through DQL also.

Overview on virtual document:

Virtual document provides a way for combining documents in various formats into one consolidated document. For e.g. one word document, one pdf document and one image can be combined to form one virtual document. There is no limitation regarding nesting of documents. One particular version or else all of the versions of a component can be combined with a virtual document. Two object types are used to store information about virtual documents. They are:

  1. Containment Object Type: It stores the information that links a component to a virtual document. Every time a component is added to a virtual document, a containment object is created for that component. The attributes of this object type can be set by the methods AppendPart, InsertPart, UpdatePart.
  2. Assembly Object Type:  An assembly object provides a snapshot of a virtual document at a given instance.

Creation of a virtual document using DFC:

A document can be converted to a virtual document by invoking the method setIsVirtualDocument on it. This method sets the r_is_virtual_doc of the document.

Note: Virtual documents can also be created using clients such as Webtop, DA etc as well as through DQL.

Requirement in the project:

Consider there are three main documents A, B and C. Essentially, A, B and C represent different contracts. Consider another set of documents A1, A2, A3, B1, B2, B3, C1, C2 and C3. A1, A2 and A3 are directly related to A, B1, B2 and B2 are directly related to B, C1, C2 and C3 are directly related to C. Also, A is related to B (A is child, B is parent), B is related to C (B is child and C is parent), and C is related to A (C is child and A is parent). The documents being referred here are Documentum documents of a certain system-defined or user-defined document type.

As per the requirements:

  1. For every new version of the documents the existing relations should be valid.
  2. From the document A, we should be able to navigate to A1, A2 and A3 and also to the documents B and C. Similarly for B and C.
  3. Depending on a particular attribute of main documents (A, B and C), there should be dynamic creation or deletion of relationships between contracts.

Resolution of requirement # 1:

Issue encountered:

Documentation says that when a dm_relation object is created with attribute values permanent_link = TRUE and child_label = ‘Current’ then for every new version of parent or child a new instance of the dm_relation object is created and the relation is created between the latest versions of child object and parent object. But on implementation of the same, always the latest version of the parent object was related to child object between which the relation was initially created.

Issue resolution:

To maintain the relation across the current versions of document and for easy navigation from parent to child documents the concept of virtual documents in addition to that of relationship was used.

All the main documents A, B and C were converted to virtual documents. The child documents A1, A2 and A3 were added as children to the newly converted virtual document A. For this the following DFC methods were used in the same order as specified:

  1. asVirtualDocument(lateBindingValue, followRootAssembly): This method is invoked on a virtual document (in this case on A, B and C) and it returns the virtual document representation of the virtual document object on which it is invoked. The parameters it takes are2.   getRootNode(): This method is invoked on the virtual document representation of a virtual document. It returns the root node of the virtual document. The root node is essentially the virtual document which is at the topmost hierarchy of virtual document tree. (In our case A, B and C are root nodes)
    1. lateBindingValue – the version label of the virtual document. To meet our requirement the value should be “Current”.
    2. folowRootassembly: If the value is set to TRUE, the assembly specified by the root node will be used as the virtual document.
    3. getRootNode(): This method is invoked on the virtual document representation of a virtual document. It returns the root node of the virtual document. The root node is essentially the virtual document which is at the topmost hierarchy of virtual document tree. (In our case A, B and C are root nodes
  2. addNode(parentNode, insertAfterNode, objectChronId, binding, followAssembly, overrideLateBindingValue): This method is invoked on the root node of a virtual document. This method adds a new node to the virtual document on which it is invoked. The parameters it takes are:
  • parentNode: The root node.
  • insertAfterNode: A virtual document node that will immediately precede the new node in the virtual document’s hierarchy. If this parameter is null, the new node is placed as the first child of parentNode.
  • objectChronId: i_chronicle_id of the document which is to be added as child to the virtual document. (In or case i_chronicle_id of A1, A2, A3, B1, B2, B3, C1, C2 and C3).
  • binding: The version label of the version of the child document with which we want to bind the child document with the virtual document.
  • followAssembly: It is set to TRUE if the follow_assembly attribute has to be set to TRUE for the component.
  • overrideLateBindingValue: It is set to TRUE if the version label identified in binding is to be used to resolve late-bound descendents of this component.

So using the concept of virtual document always the current versions of document are present in the parent virtual document. Thus the current versions of A and A1, A2, A3 are always related. And since A has been converted to virtual document, we can navigate to A1, A2 and A3 by just clicking on A.

Resolution of requirement # 2:

Now using the concept of relationship, a relation was created between A and B, B and C, A and C each. Thus navigation across the different contracts A, B and C was possible. Pictorially this can be shown as:


In the above figure the arrow denotes the relationship between two documents.

Resolution of requirement #3:

Requirement #3 states that there should be dynamic creation or deletion of relations between main documents depending on a particular attribute, say, attr. The value of attr for, let’s say, document A determines to which document, A will act as child. If the value of attr for document A is changed so as to imply that A and B are no longer related, then the relation object existing between A and B should be destroyed. If the new value points toward new document D, then a relation has to be created between A and D.

So the change in value of that particular attribute needs to be intercepted. The interception can be done as follows:

  1. Write a TBO (Type based object) for the document type to which A belongs to.                

 Note: For details on TBO refer BusinessObjectsDevelopersGuide.pdf provided by Documentum.

  1. In the TBO, override the method setString(attribute name, value of attribute), if the attribute attr is single-valued attribute or appendString(attribute name, value of attribute), if it is multi-valued attribute. These two methods captures all the attributes and their values for a document type. setString captures the single-valued attributes while appendString captures the multi-valued attributes.
  2. In either of the method, compare the old value of attribute attr with the new one. If there’s any change destroy all the existing relations which involves the document A as child. This can be done using the DFC method removeParentRelative(relationTypeName,parentId,childLabel).  Invoke this method on A. The parameters it takes are:Now use the method addParentRelative as explained, to relate document D as parent to document A.
    1. relationTypeName – Name of the relation object.
    2. parentId – r_object_id of parent object.
    3. childLabel – version label of child object.
  3. Every time the value is changed for attribute attr and the document is saved, the corresponding TBO is invoked and the above mentioned methods will be executed. Thus dynamic creation or deletion of relations can be achieved.

Conclusion: Thus the concept of relationships and virtual documents can be used together to relate objects in Documentum using Documentum Foundation Classes (DFC).


October 24, 2010 Comments off

DQL is used by administrators, developers, and applications to retrieve  information from the Content Server .DQL statements operate on objects and sometimes on tables/rows while SQL statements only operate on tables/rows.

Building blocks of a DQL statement  includes,

Ø  Literals, which describes the literal formats for the Documentum datatypes

Literals are values that are interpreted by the server exactly as they are entered. Content Server recognizes .Five types of literals:

§  Integer literals

§  Floating point literals

§  Character string literals

§  ID literals

§  Date literals

Ø  Special keywords which describes the special keywords that can be used in DQL

Special keywords have special meanings for Content Server when used in a DQL query. (They cannot be used in API methods.) Some  keywords are:

§  USER, which identifies the current user

§  TRUE and FALSE, which represent the Boolean true and false.

§  DM_SESSION_DD_LOCALE, which represents the data dictionary locale.

Ø  Functions which describes the functions that can be used in DQL queries

Functions are operations on values. DQL recognizes three groups of functions and two unique functions:

  • Scalar functions: Scalar functions operate on one value and return one value.
  • Aggregate functions: Aggregate functions operate on a set of values and return  one value.
  • Date functions:Date functions operate on date values.
  • The ID function:The ID function, a unique function recognized by DQL, is used in   the FOLDER and CABINET predicates and in the IN DOCUMENT and IN ASSEMBLY clauses.
  • The MFILE_URL function:The MFILE_URL function returns URLs to content files and   renditions in particular format

Ø  Predicates  which describes the predicates that can be used in expressions in queries

Predicates are used in WHERE clauses to restrict the objects returned by a query. The WHERE clause          defines criteria that each object must meet. Predicates are the verbs within the expression that define the        criteria.

DQL recognizes these predicates:

Arithmetic operators

Comparison operators

Column and attribute predicates

SysObject predicates

Ø  Logical operators describes the logical operators supported by DQL

Logical operators are used in WHERE clauses. DQL recognizes three logical operators:

  • AND
  • OR
  • NOT

Any number of expressions can be joined together with logical operators. Content Server imposes no limit. (Underlying RDBMS may impose a limit.) The  resulting complex expression is evaluated from left to right in the order of precedence of the operators. This order, from highest to lowest, is: NOT,AND,OR

Ø  DQL reserved words which is a  list of the words reserved in DQL

DQL reserved words should be enclosed in double quotes when using in a DQL query. some keywords are

  • ALL
Categories: DOCUMENTUM Tags: , ,


October 24, 2010 Comments off

DQL is the acronym for Document Query Language, the SQL-like language that you use to query the Docbase. Using DQL, you can retrieve, update, and delete objects and create new objects. You can also use DQL to access registered tables—tables in the underlying RDBMS that are known to eContent Server but that are not part of the Docbase.
Some special key words of DQL :
• User
• True
• False
• Any
• Type
• Folder
• Cabinet
• All
• Id
• Append
• Truncate
• Insert………….

Eg 1
Select * from dm_document where owner_name = User — User here refers to user of the session
Eg 2
SELECT “r_object_id” FROM “dm_sysobject”
WHERE ANY “authors” = ’suresh’
Here, authors is repeating valued field and the query returns all the rows which have “suresh” as one of the “authors”
Eg 3
Update DQLs
UPDATE “dm_document” OBJECTS
APPEND authors=”Prem”
WHERE “title” = ’ACS’
This adds a new author to the end of the list. Ie already if 3 authors are there, this becomes the 4th.
Eg 4
To delete a value in a repeating attribute, use the remove option as the update clause and specify the index value associated with the value.UPDATE “nm_document’ OBJECT
REMOVE authors[4]
WHERE “title” = ’OLD FILE’
Eg 5
Consider three types of document – doctype1, doctype2 and doctype3. To get documents of type doctype1 or doctype3 we use the “Type” key word.
Select * from dm_document WHERE Type (doctype1) OR Type (doctype3)
Eg 6
To query from specific folders we use the folder key word.
Everything in documentum is out in folders which are there in Cabinet.
Select * from dm_document
WHERE Folder(‘/cabinet/folder1’);
Select * from dm_document
WHERE Folder(‘/cabinet/folder1’, descend);
If the Descend key word is NOT used, it queries only the folder specified but not subfolders underneath the folder
CREATE —- used to create object types
CREATE…OBJECT — used to create instances
CREATE dm_document Object
SETFILE=”D:\docs” with
Content_format = “MSW8”;

Categories: DOCUMENTUM Tags: , , ,

Unlocking Documents in Documentum using DQL and API

March 28, 2010 Comments off
The process which can be used to unlock the document is described in below flowchart. It is a two step process. In step1, we have to obtain the object ID of the document using DQL. In step2, Document has to be unlocked using API command.

Unlock Documents

Categories: DOCUMENTUM Tags: , , ,
%d bloggers like this: