Custom Types in Documentum(转)
From:http://www.packtpub.com/article/custom-types-in-documentum
Custom Types in Documentum
In this article by Pawan Kumar, we look at the Custom Types in Documentum. We will see how to manage the custom types by looking at how to create a custom type and modify the custom type. We have also introduced the concept of data dictionary, which stores additional information about custom types.
Custom Types
Documentum provides a large number of built-in object types that support the functionality of the platform. Some object types are general purpose and can be used for business purposes as well. However, all possible business needs can neither be anticipated nor supported by default. Therefore, Documentum allows creation of new object types, which are called custom types. This article addresses creation and management of custom types.
Before reading this article, it would be helpful to know about Objects and Types, since the majority of the concepts pertaining to object types apply here as well. Some concepts are explained here.
Managing Custom Types
A user-defined object type is called a custom type and the user-defined properties are called custom properties. Properties are also known as attributes. Custom types can be created, modified, and removed as long as certain rules are followed. This section describes the detail around managing custom types.
Creating a Custom Type
A custom type can be created using Documentum Application Builder (DAB), using Documentum Administrator (DA), or using DQL/API scripts. DAB is the most commonly used application for creating custom types since it fully supports the data dictionary (see Data Dictionary later in this article) and it has a Graphical User Interface (GUI) specifically designed for creating and managing custom types.
Further, DAB can also be used for packaging the types into a DocApp. The following screenshot shows the DAB screen for creating and updating a custom type:
DA provides basic support for managing custom types. For example, DA does not provide an interface for defining value assistance for a property. The following screenshot shows the screen for creating and updating custom types in DA:
Creating a custom type is a privileged operation and only the users with following privileges can do so:
- Create Type
- Sysadmin
- Superuser
The user creating the type becomes the owner of the type.
A custom type can extend an existing type through inheritance (see Type Hierarchy in Documentum). A new custom type can have an existing custom type or one of the sets of Documentum object types as its supertype. The most common supertype for a new custom type for representing documents is dm_document.
It is also possible to create a custom type without a supertype. Such a type is called a NULL type. Only a user with Superuser privilege can create a NULL type. A NULL type is useful for storing data that does not need the usual object management features such as versioning. There are several built-in types that are NULL types such as dm_user, dm_session, and dm_alias_set. If a custom type is intended to only store non-versionable data, a NULL type may be appropriate for this purpose. Recall that any given type uses up to two tables (one for single-valued properties and one for repeating) of its own for storing non-inherited properties of its objects. There are additional views for retrieving all the properties together. The following key information is needed or captured in DAB when creating a new custom type:
Info
Description
Name
Name of the type. A type name must be unique (caseinsensitive) in the repository and can be up to 27 characterslong. The additional constraints on the type name are that itcannot contain a space or punctuation nor can it be same asany DQL reserved word, such as SELECT or WHERE.
Further, it cannot start with dm_, dmi, dmr_, a number,
space, or a single quote. It is recommended that a custom
prefix be used for custom type names to distinguish them
from the other types.
Creator
The user creating the type.
Supertype
The supertype of the new type. This can be NULL.
Label
User-friendly version of the name, for display purposes in
Documentum client applications.
Default Lifecycle
A lifecycle that can be attached to a document of this type,
without identifying the lifecycle explicitly.
Default Storage Area
A storage area identifies where the content files are stored
for objects. The default storage area identifies where the
content files for objects of this type will be stored by default.
Default Permission Set
The default permission set is used when the default ACL
mode for the Content Server is set to Type.
In this case, a new object of this type gets this permission set.
Template Document
One or more template documents can be created for the
type, which are available to users when they are creating a
new object of this type. The template documents are stored
in the Templates cabinet in Documentum repository.
Events for Types
An event is an operation on an object or something that happens in an application. A system event is an event that is recognized and is auditable by the Content Server. For example, checking on a particular document in a system event. Promoting or demoting an object in a lifecycle is also a system event.
On the other hand, an application event is recognized and is auditable only by the application. The application events can be defined using DAB. For example, an application event can be used to hold off workflow activities based on external dependencies such as conditions in other systems.
Suppose that a workflow activity requires a performer to review a document. However, the performer needs access to data in another system in order to complete this task. An application event can be sent to the performer's inbox to trigger the activity once the required data is available in the other system.
The following screenshot displays the DAB screen for managing application events:
Note that events are also inherited from supertypes just like properties. The events shown in the previous screenshot, are inherited from dm_document—these are system events and cannot be modified or removed.
This article has been extracted from: Documentum Content Management Foundations: EMC Proven Professional Certification Exam E20-120 Study Guide
Learn the technical fundamentals of the EMC Documentum platform while effectively preparing for the E20-120 exam
- Technical foundations of the Documentum platform
- Thorough preparation guide for the E20-120 exam
- Complete coverage of the prescribed syllabus
- Illustrated examples and practice questions on each topic
- Two full-length practice tests with answers
For more information, please visit:
http://www.PacktPub.com/Documentum-Certification/book
Properties
An object type inherits all the properties of its supertype. Custom properties can be created for custom types, with each property being defined in the following manner using DAB:
The following screenshot shows the DAB screen for managing a custom attribute:
Info
Description
Name
The name of a property must be unique within the type, including inherited properties. The property should be named in all lower case letters and 'select', 'from', and 'where' are not valid names. Further, a property name cannot start with dm_, a_, i_, r_, a number, a space, or a single quote.
Label
User-friendly version of the name, for display purposes in
Documentum client applications.
Data Type
The data type of the property constrains the types of values this property can take. The allowed data types are integer, boolean, string, double, time, and ID.
Length
Length of the property if the data type is string.
Repeating
Whether this is a repeating property or single-valued.
Default Value
Default value for this property.
Input Mask
The input mask is used for validation and provides a pattern for valid values for this property. The mask is specified using the following characters with special meaning in addition to the regular characters:
#: A numeric digit 0-9
A: An alphanumeric character including a-z A-Z 0-9
&: Any ASCII character
?: Any alphabetical character a-z A-Z
U: Similar to ? but automatically converted to upper case before saving
L: Similar to ? but automatically converted to lower case before saving For example, suppose that an account number consists of 8 characters where the first three characters must be alphabetic and the remainder can be alphanumeric. An input mask for this property can be specified as ???AAAAA.
Search Support for Properties
Some information about properties can be provided to support the user interface for searching on this custom type.
Info
Description
Searchable
Whether this property is searchable
Default Search Value
Default value for the search field for this property
Allowed Search Operators
The types of matching that can be done on this property
for searching, such as =, <>, 'begins with', etc.
Default Search Operator
Which search operator among the allowed ones should
be selected by default
Displaying Properties
Client applications can utilize display configurations to display properties for different object types in different ways. Display configurations are created using DAB. Documentum Desktop (also known as Documentum Desktop Client) and WDK applications utilize display configurations extensively. WDK applications such as Webtop use display configurations to include custom properties in the standard interface without writing any additional user interface code.
For example, Webtop can display custom properties in an editable form on a separate tab on the properties page using a display configuration. The following screenshot shows creation of a Display Configuration named Resume. When the properties of an object of type dq_resume are viewed in Webtop, a separate tab named Resume will use this display configuration to display the attributes included in it.
A display configuration specifies when certain properties should be displayed and how their display should be organized. Each display configuration specifies three aspects:
- Scope determines when to use this display configuration. It can be a combination of an application and a role, implying that this configuration should be used when the specified role is accessing an object of this type in the specified Documentum application. Thus, even within the same application it is possible to create different views of the same object for different roles.
- For each scope, multiple configurations can be defined. For example, Webtop displays the configurations as tabs on the properties view of objects.
- For each configuration, an ordered list of properties is specified, which constitutes the configuration. These properties are displayed together in the Documentum application.
Note that, implicitly, the properties not included in display configurations are not displayed on the application interface. Thus, display configurations can be considered as a way of exposing or hiding custom properties.
Validation
Constraints are conditions that must be met by objects and properties to be valid. For example, a custom type may represent an account with a property account ID. Then a potential constraint on this type is that the account ID property is required to be unique within the repository. Constraints for custom types can occur in the following forms:
Constraint Type
Description
Primary Key
The primary key uniquely identifies an object within the repository. There is only one primary key for a type.
Unique Key
A unique key is unique among all the objects of this type in the repository. There can be multiple unique keys for a type.
Foreign Key
A foreign key establishes a constraint between properties of two types. A Sysadmin privilege is required to create a foreign key constraint.
Check
A check constraint is a condition expressed as a Docbasic
expression or a routine that evaluates to true or false.
An error message can be specified for each constraint and it can be displayed to the user when the corresponding constraint is violated. Optionally, each constraint can be flagged to be enforced in which case the client application should enforce the constraint.
The constraints can also be specified at the property level where the constraint is specified as a Docbasic expression. An error message and enforcement flag can also be specified at the property level.
Value Assistance
When users need to specify values for object properties through client applications it may be desirable, due to business reasons, to limit the values that can be specified for a property. For example, if a property represents a country name its underlying data type is string but only the country names are meaningful values for this property. When the user needs to specify a country name, the application can limit the value to one of the actual country names. This ability is supported by a feature known as value assistance.
Value assistance specifies a list of valid values for a property that can be used by client applications to facilitate valid user input. The list of valid values can be an explicitly fixed list or a DQL query that returns a list of appropriate values from a data source—objects or database tables. The following screenshot shows the DAB screen for managing value assistance for an attribute named experience on custom type dq_resume:
It is also possible to use one of many lists for value assistance on a property. The list to use is decided dynamically based on certain conditions. One of these lists is identified as the default list and the others are identified as conditional. Each conditional list is associated with a condition and is used when that condition is true. The default list is used when none of the conditions is true.
There are two other options that affect the behavior of these lists. One specifies whether the queries can be cached. Caching queries improves performance by storing the lists retrieved for value assistance. However, if the data being queried is modified, the changes are not available in the application until the cache has been refreshed.
The other option specifies whether the list of values is complete—this essentially specifies whether the user can enter a value other than those in the list, for example using a combo list or box. This option is useful when a set of initial or most frequently used values is known, but there may be cases when other values are acceptable but not known beforehand.
Note that value assistance cannot be specified for Boolean properties. A Boolean property can only be true or false.
Value Mapping
Another useful feature for client applications is value mapping. A value mapping defines a correspondence between stored values and labels to display for those values. Suppose that a property represents a color and stores the value in RGB format. In this case, a value mapping can be useful to help the user view/select an appropriate value. For example, a stored value FF0000 may be mapped to Red, which makes more sense to most users.
Note that $value is a useful keyword that can utilize user-specified single values in a validation error message or in a value assistance query at run time. For example, SELECT title from book WHERE author = $value(user_author) and category = $value(user_category). This query retrieves book titles where the author and category of the books are provided by the user.
Modifying a Custom Type
Once a custom type has been created, a need may arise to alter it. This may happen when an unforeseen need arises or the requirements change.
Modifying a custom type is a privileged operation and only the type owner or a user with Superuser privilege can modify a custom type. The default Documentum types cannot be modified.
A custom type can be modified only in the following ways:
- The type can be dropped (removed). Dropping a type is allowed only when there are no objects of this type and this type has no subtypes.
- A new property can be added to the type.
- A non-inherited property can be dropped (removed) from the type.
- The length of a non-inherited string property can be increased.
When a custom type is modified, it automatically affects its objects, its subtypes, and objects of its subtypes.
Just like objects, a type needs to be checked in after it has been modified. However, remember that a type cannot be versioned and no history of type changes is retained (other than potentially through audit trails). The type exists only in its most recent form.
It is possible to change the type of an object, though that does not change the type itself. The type of an object can only be changed to the immediate supertype or an immediate subtype of the existing type. For example: change my_doc objects to dm_document WHERE object_name = 'xyzreport.pdf'
Using Custom Types
Custom types can be used just like the built-in Documentum types except for the restrictions described earlier. Much of the additional information specified about custom types is stored in the data dictionary.
Data Dictionary
The data dictionary consists of a set of types whose objects store information about types, such as constraints for properties, default lifecycle, default property values, value assistance, mapping info, and localized text. Since the data dictionary is stored in the repository, it is available to all client applications.
Note that the data dictionary is available for the client applications to use and the Content Server does use the data dictionary for its operation.
The data dictionary information is often cached by applications. In order to refresh this cached information with new changes, the data dictionary can be published. The API method publish_dd can be used to publish the data dictionary.
This article has been extracted from: Documentum Content Management Foundations: EMC Proven Professional Certification Exam E20-120 Study Guide
Learn the technical fundamentals of the EMC Documentum platform while effectively preparing for the E20-120 exam
- Technical foundations of the Documentum platform
- Thorough preparation guide for the E20-120 exam
- Complete coverage of the prescribed syllabus
- Illustrated examples and practice questions on each topic
- Two full-length practice tests with answers
For more information, please visit:
http://www.PacktPub.com/Documentum-Certification/book
About the Author
Pawan Kumar is a Technical Architect with current expertise in Enterprise Content Management with EMC Documentum. He has an MS in Computer Science from University of North Carolina at Chapel Hill and a BS in Electrical Engineering from the Indian Institute of Technology, New Delhi (India).
Pawan has experience developing products as well as delivering business solutions on the Documentum platform and has created two products for this platform. He is intimately familiar with effective processes and tools for achieving business objectives through Documentum-based technology solutions. He has led and executed requirements and design workshops, architecture design, scoping, estimation, project planning, resource planning, technical design, software development, software testing, solution roll-out, and ongoing support for the deployed solutions. Pawan has been architecting, designing, and developing enterprise applications for ten years. He has developed software systems for financial services, healthcare, pharmaceutical, logistics, energy services, and retail industries. His expertise spans solution architecture, document management, system integration, web content management, business process management, imaging and input management, and custom application development.
Currently, Pawan provides consulting and training services through doQuent (http://doquent.com), which was founded with the vision of enabling client success in content-related business initiatives. He also believes in giving back to the community. He founded the free online Documentum community dm_cram (http://dmcram.org), which is a test preparation resource for Documentum exams. He is also an active contributor to the Documentum-users Yahoo! User group, where Documentum community members seek help for their technical challenges. He can be reached at pk@doquent.com.
