Home > Resources > Articles > Custom ECM Solutions > Introduction to Documentum Composer

Introduction to Documentum Composer

October 10, 2008 by Blue Fish Development Group

As part of the new Documentum 6 platform, EMC has introduced Documentum Composer, a new application for packaging and deploying Documentum artifacts. This article aims to provide an initial introduction to the Composer application, including some core concepts, a discussion of major changes from the world of Documentum Application Builder (DAB) and Documentum Application Installer (DAI), and some tips and tricks to make using Composer easier and less problematic.

Overview

As part of the new Documentum 6 platform, EMC has introduced Documentum Composer, a new application for
packaging and deploying Documentum artifacts. It is meant to replace Documentum Application Builder and
Documentum Application Installer with a single application for developing, building, and deploying
Documentum projects into a repository.

It is important to note that Composer is a completely new application, built from scratch using the Eclipse
platform. It improves upon DAB and DAI in a number of ways, including an open, standardized XML file format;
a more robust and customizable compilation and installation paradigm; and improved visibility for developers
into the application’s operation and data.

Overall, Composer is a huge leap forward for the Documentum installation paradigm, but it is still maturing
as an application. In many cases, Composer will prove a more useful tool than DAB or DAI, but there are
probably still cases where DAB and DAI might be needed, at least temporarily, where Composer’s functionality
or reliability fall short. Careful planning and attention to detail can help to make Composer a valuable
tool for predictable, repeatable installation into Documentum repositories, despite some of the gaps and
pitfalls still present.

This article aims to provide an initial introduction to the Composer application, including some core
concepts, a discussion of major changes from the world of DAB and DAI, and some tips and tricks to make
using Composer easier and less problematic.

Note:
This article was written based on Documentum Composer 6.0 SP1. Subsequent Composer versions are known
to improve on some of the shortcomings identified here.

Core Concepts

Artifact

An
artifact
is a single unit of Composer code which usually describes a single object to be installed into a Documentum
repository. An artifact might be a custom object type, a document, an ACL, a user, a group, or any number of
other Documentum objects.

An artifact can be imported into a Composer project from an existing repository, or it can be created from
scratch using various Composer editors and local file system content.

Project

A
project
is a single, installable collection of artifacts. It corresponds roughly to the DocApp concept from the
DAB/DAI world. The only way to install artifacts into a repository using Composer is to install a Composer
project containing those artifacts. Unlike DAB/DAI, it is not possible to manually checkout or checkin
individual artifacts using Composer; one must install the entire project into the repository.

There are a number of ways to create and populate a project using Composer:

  • A project can be imported into Composer from an existing repository project or DocApp.
  • A project can be imported from an existing Composer project on the file system.
  • A project can be created from scratch using artifacts from a repository as well as artifacts created
    from scratch.

Workspace

One big improvement over DAB/DAI is that Composer provides support for keeping multiple projects open at the
same time, by way of the Eclipse workspace paradigm. A
workspace
is a collection of projects which can be viewed and developed actively at the same time within a single
instance of Composer.

Although composer does not prevent you from dragging and dropping artifacts from one project to another,
it is NOT supported. In some cases it will work, but in most cases necessary prerequisites, dependencies,
or installation parameters will be lost. Always examine the XML for any artifacts that have been dragged
and dropped into a Composer project, to be certain that locations and other references are intact and
correct. It may be necessary to clean and build your project to discover some problems, while others
will not be evident until installation or later.

Note:
It is strongly recommended to keep your Composer workspace separate from any other Eclipse workspaces that
may already exist.

Installation Parameters

In order to make it possible to drive certain installation behavior based on parameters entered at the time
of installation, Composer utilizes
installation parameters
. An installation parameter can be created to represent a folder location, for example, and then that
location can be entered at runtime when installing the project into a repository.

Some features of Composer require installation parameters in order to function, but in these cases the
parameter is created and given a default value automatically. In other cases, you may wish to create your
own installation parameters.

If a project utilizes multiple installation parameters, it can be useful to provide values for all of these
parameters using a single file. This file is called an
Installation Parameter File
, and it can be specified as part of the installation wizard.

Major Changes from DAB/DAI

Overall, Composer is a vast improvement over DAB/DAI, because it provides so much more visibility into and
control over what is happening every step of the way. The architecture is far more robust and extensible,
and this can only mean good things for the future of Documentum configuration management.

The application is still maturing, however, and it shows. There are still many ways to accidentally “break”
your artifacts or your project. Some much-needed custom editors are still missing, occasionally requiring
manual editing of XML which is error-prone and time-consuming. Other editors are buggy or not fully
functional, and at times the installation parameters functionality can be unreliable. Hopefully these issues
will be addressed in future releases.

Some of the key improvements and changes are discussed below.

Open File Formats

All artifacts that make up a Composer project are represented using a standardized XML file format.
Documentum has abandoned the proprietary DAB/DAI file formats, which completely obfuscated their contents.
The new XML-based files provide visibility into what is in the project, making it easier to troubleshoot and
resolve problems. Furthermore, the XML format makes it simple to track and compare revisions to your
Composer project using source control.

Eclipse Platform

You might be familiar with the Eclipse Integrated Development Environment (IDE), which is popular among Java
developers for a variety of reasons. But Eclipse is more than just an IDE; it is also a powerful open-source
software development platform upon which a wide variety of rich client applications can be built.

Composer is built on the Eclipse platform, and the installation includes a bundled Eclipse environment.
Composer is deployed as a set of Eclipse plugins within this embedded Eclipse environment, such that running
the eclipse.exe executable automatically launches Composer.

Fig. 1: Composer Main Window


Figure 1:
Composer Main Window

Composer leverages the
Eclipse Modeling Framework
(EMF), which is “a powerful modeling framework and code generation facility for building tools and other
applications based on a structured data model”. Like the rest of the Eclipse platform, EMF is open source.
It provides a wide variety of modeling and code generation capabilities which enable Composer to be
leveraged across multiple platforms and environments.

Although it is possible to run Eclipse-based applications as plugins within your Eclipse IDE, it is not
recommended to install the Composer plugins directly into an existing Eclipse environment in this way.
Composer is meant to run within its own separate installation of Eclipse.

Compilation Paradigm

One of the benefits of the Eclipse platform is that it offers a number of paradigms that are familiar to
developers. Composer utilizes the standard Eclipse build paradigm, with its own custom builder, in order to
provide real-time validation and compilation of artifacts before they are installed. Composer Projects must
be “built” before being “installed”, enabling offline discovery of some problems before attempting to
install into the repository.

The project directory structure is broken out in support of this compilation paradigm, with separate
directories for artifact source code, artifact content, and compiled binaries. Refer to the
Anatomy of a Composer Project
section for a full discussion of the project directory structure.

By default, Eclipse is configured to automatically build your Composer project, which means that as artifact
source files are saved, Eclipse will attempt to compile the project and will report validation or
compilation problems. If you Clean your project, all compiled resources will be deleted and rebuilt
automatically. If you turn off automatic compilation, you will need to remember to manually build the
project. If you attempt to install your project, it will be built automatically.

Fig. 2: Composer Project Menu


Figure 2:
Composer Project Menu

The
Problems
tab reports errors, warnings, and informational messages reported while compiling the artifacts in your
project. These kinds of problems typically mean something is wrong with your artifacts or their metadata.

Fig. 3: Composer Problems Tab


Figure 3:
Composer Problems Tab

The
Error Log
tab reports errors encountered within the Composer or Eclipse code. Errors point to a Composer bug or
configuration problem, and are typically unrelated to your project. Many errors are simply informational
and do not adversely affect Composer’s execution. Composer 6.5 minimizes the prevalence of these errors
as compared with Composer 6.0.

Fig. 4: Composer Error Log Tab


Figure 4:
Composer Error Log Tab

Installation Paradigm

In the DAB/DAI world, DocApps and DocApp artifacts could be checked out and checked in. In Composer, the
paradigm is one of “installation”, with no explicit control over checkout/checkin of individual artifacts.
This means it is not possible to manually checkout and checkin project artifacts to and from the repository
without installing the entire project.

To install a Composer project, right click on the project in the Navigator pane, and select
Install Documentum Project…

Fig. 5: Composer Project Context Menu


Figure 5:
Composer Project Context Menu

Selecting
Install Documentum Project…
will launch the project installation dialog, which gathers installation options prior to installing the
project to a repository. You must first login to a repository before the wizard will allow you to continue.

Fig. 6: Composer Project Installation Wizard


Figure 6:
Composer Project Installation Wizard

Better Logging

Another major improvement over DAB/DAI is Composer’s logging. Composer provides much better and more
detailed logging of every activity, as well as full Java stack traces when something goes wrong. Together
these provide greater visibility into what’s happening as it is happening.

Whereas DAB/DAI provided decent logging of the installation process, there was no logging of compilation or
other activities taking place while working on a project, such as import or modification of existing
artifacts. Composer provides logging for all of these activities, making it much easier to track down issues
before they make it into a repository.

Composer’s log file can be found in the %TEMP%/documentum directory. Composer creates a new
log for every Composer session, so it is typically most expedient to sort the directory by date and look
at the most recent log file found.

Headless Eclipse Mode

Composer can be run in “headless Eclipse mode”, which enables command-line scripting and automation of
project installation. This feature, new to Composer, provides for self-contained, fully automated deployment
of projects into a repository, without the need for a previous DFC installation or DMCL client.

Anatomy of a Composer Project

Files and File Types

There are a variety of files and file types that make up a Composer project.

  • Eclipse project files (
    *.project,
    *.classpath)
  • Composer project files (
    *.dmproject,
    *.template)
  • Artifact XML source files (
    *.aliasset,
    *.module,
    *.aspecttype,
    *.folder,
    *.format,
    *.group,
    *.jardef,
    *.javalibrary,
    *.job,
    *.lifecycle,
    *.method,
    *.module,
    *.acl,
    *.procedure,
    *.relation,
    *.relationtype,
    *.role,
    *.sysobject,
    *.type, and so forth)
  • Installation Parameter definition files (*.parameter)
  • Content files (*.* in the /content subdirectory)
  • DAR Definition file (*.dardef in the /dar subdirectory)
  • Compiled artifact files (*.artifact in the /bin subdirectory)
  • Compiled DAR file (*.dar in the /bin-dar subdirectory)

Folder Structure

Each Composer project is broken down into a standard folder structure, with different folders serving
different purposes. Some folders contain XML source code, some contain content files, and others contain
compiled descriptors and binaries. The project folder structure can be seen in the Navigator pane of
Composer.

Fig. 7: Composer Navigator Pane


Figure 7:
Composer Navigator Pane

Hidden Resources

By default, the Composer interface hides certain resources that are not part of the core user-facing
functionality. It can sometimes be useful to reveal these hidden resources in order to troubleshoot and
resolve problems, but ordinarily it is best to keep these resources hidden to avoid tampering with them
inadvertantly.

In order to function properly, Composer relies on a hidden project that it creates in your workspace
automatically the first time you try to create a new project. This hidden project is called
DocumentumCoreProject, and it must be present in your workspace in order
for Composer to function properly.

Note:
If you wish to create a new workspace, simply moving your custom projects into it will not be sufficient.
You must also move the DocumentumCoreProject, or else let Composer create a new one by creating a new
project.

In order to reveal the hidden DocumentumCoreProject and other hidden resources, launch the Filters dialog
from the pulldown menu in the upper right corner of the Navigator pane.

Fig. 8: Composer Navigator Pane Pulldown Menu


Figure 8:
Composer Navigator Pane Pulldown Menu

The Filters dialog can be used to enable or disable various filters, which will have the effect of hiding or
revealing various resources in the Navigator pane.

Fig. 9: Composer Filters Dialog


Figure 9:
Composer Filters Dialog

Fig. 10: Composer Filters Dialog with All Filters Disabled


Figure 10:
Composer Filters Dialog with All Filters Disabled

The Navigator pane shown below has had all filters disabled, revealing all hidden projects, folders, and
files.

Fig. 11: Composer Navigator Panel with All Filters Disabled


Figure 11:
Composer Navigator Panel with All Filters Disabled

Folders

The
/Artifacts
folder contains the XML artifact “source files” from which your Composer project is built.

The
/content
folder contains the binary and other content files used to back artifacts that require content, such as
documents. The folder structure within the
/content
folder is created automatically by Composer as content is imported into the project from repositories and
the local file system. The
/content
folder structure is based on a hash structure, but it is possible to move a content file to a more
user-friendly location within your project by updating the content location reference in the artifact XML
file for the artifact. This can be useful in order to provide well-defined content locations within your
project, so that an Ant build, for example, could deposit updated BOF JARs or customized XML files into the
content location, then easily install the project containing those artifacts into a repository.

The folders below contain “compiled”
.artifact
files, built based on the XML and other project metadata described above. These folders would typically NOT
be checked in to source control or distributed in a source code package.

  • /dfs-bin
  • /dfs-gen-src
  • /bin-dar
  • /bin

The
/dar
folder contains XML source required by the project as a whole, including an object type definition and
default installation settings for the project.

  • dmc_dar.type
    XML describing the dmc_dar object type, which is needed in order to install a project into a repository.
    The contents of this file typically do not need to be edited directly.
  • default.dardef
    XML describing various default settings to use for installation into a repository. This file contains
    references to many other artifacts, and can sometimes require editing in order resolve broken references
    or to include missing artifacts.

The
/src
folder is created automatically by Composer. By default it is empty. It may be possible to leverage this
folder to develop Java source code to be used by your project, but this is beyond the scope of this article.

The
/Installation Parameter Files
folder is created automatically by Composer. By default it is empty, but it can be used to develop parameter
files containing parameter values to be used upon installation.

More About Artifacts

Artifact Editors

Composer includes custom editors for a wide variety of Documentum artifacts. These editors enable you to
specify the artifact metadata and configuration using intuitive controls. Composer comes preconfigured to
utilize custom editors for all of the following artifacts:

  • Alias Sets
  • Aspect Modules
  • Aspect Types
  • Formats
  • Installation Parameters
  • Jar Definitions
  • Java Libraries
  • Jobs
  • Lifecycles
  • Methods
  • Modules
  • Permission Sets
  • Procedures
  • Relation Types
  • SysObjects
  • Types

There are additional artifacts for which there are no custom editors. Some of these artifacts are hidden,
while others are not. It is much easier to create these artifacts by importing them from an existing
repository, but if necessary they can be created from scratch by editing XML files. These include Folders
and Relations, among others.

Artifact XML

In some cases the editors are insufficient or unstable, in which case it becomes necessary to edit the XML
source directly, using the System Editor or Text Editor. To open any artifact using an
editor other than the default, simply right-click on the artifact and select Open With.

Fig. 12: Composer Artifact Context Menu


Figure 12:
Composer Artifact Context Menu

The list below provides an overview of some of the key XML elements and attributes you may need to work
with.

  • sysObjects
    This element can be found within the <dataModel> element within an artifact’s XML, typically a
    folder artifact. It specifies which objects should be linked into that folder. The references here must
    correspond to artifacts within your project.
  • location
    This attribute can be found within the URL specified by the href attribute of the <sysobjects>
    element. It defines the folder path in the repository where this artifact should be linked, if
    applicable. Sometimes this value must be manually updated to change the location an artifact is linked,
    but don’t forget to update the <sysObject> element references to the artifact in the corresponding
    folder’s artifact XML, or the location change may not work!
  • artifactURI
    This attribute can be found within the URI specified by the uri attribute of the
    <Artifact:Artifact> element. It is a unique identifier which has no purpose other than to uniquely
    identify the artifact within the project. If your artifact was imported from an existing repository,
    this value will be the folder path from that repository. If your artifact was imported from the file
    system, this value will be the path to the content on the local file system. It is okay if this value
    refers to a location that is no longer available — it is an identifier only and is not used to specify
    any installation locations.
  • filePath
    This attribute of the <contentStore.contentEntries.value> element specifies the path within the
    project to the binary content file to use for this artifact. This value can be modified directly in the
    XML to point to a well-defined location, rather than the default location defined by Composer; just be
    sure the location you enter corresponds to real content.

Some Technical Details

Version Compatibility

It is important to understand which versions of Composer, DAB, and DAI are capable of interacting with
certain repository versions.

Composer provides support for all of the following situations, although in some cases an interim “migration
repository” must be used.

  • Create a new Composer project by importing a 5.3 DocApp archive on a file system
  • Create a new Composer project by importing a 5.3 DocApp from an existing 5.3 repository
  • Create a new Composer project by importing a 5.3 DocApp from an existing 6.0 repository
  • Create a new Composer project by importing an existing Composer project
  • Install a Composer project into a 5.3 repository.
  • Install a Composer project into a 6.0 repository.

For more details concerning DocApp migration, consult the
Migrating a repository DocApp
and
Migrating a DocApp Archive
sections of the EMC Documentum Composer Version 6 SP1.5 User Guide.

Alhough Composer is a great new paradigm shift, it is one which is still incomplete. Because of this, EMC is
still supporting DAB and DAI, and has released a version of DAB/DAI which is supported against both 5.x and
6.x repositories. To interact confidently with both D5 and D6 repositories, you must use version
5.3 SP5.5 Update 1
of DAB and DAI.

Source Control

One of the benefits of Composer’s new XML file format for artifact source is that it is now possible to
track an artifact’s version history by checking the artifact’s XML source file directly into a source
control system as changes are made.

In DAB/DAI, there were no source files representing the artifacts, and indeed the only view into these that
could be generated outside a repository was a DocApp archive, which was made up of binary files that could
not be easily compared or reviewed. This made it necessary to track an artifact’s version history directly
in the repository where it was installed and versioned, which was often insufficient and very limiting.

With Composer, it is simple to manage the entire Composer project source in a source control system.

Automated Build and Deployment

Another benefit of the Composer model is the ability to script the compilation and deployment of a project
and its artifacts. This makes it possible to develop truly integrated scripts for building and deploying
Documentum projects in an automated fashion. As this model matures, we should start to see projects with
fully integrated Ant or Maven scripts for building Java source code and then utilizing the output of that
build to deploy updated JARs and other artifacts into a repository.

This automation capability will make it easy for development teams to automatically deploy new software
releases to the repository, in addition to any automated deployment to application servers, method servers,
and elsewhere.

Tips and Tricks

  • In certain situations, it may be necessary to inspect and modify the artifact XML files in order to
    resolve various problems or work around certain Composer limitations. Ordinary usage, however, should
    not require delving into the XML.
  • When importing folders and objects, you must also import the folders containing those folders and
    objects, all the way up to the root cabinet, or you risk the folders being linked into the application
    folder instead of the location you intended.
  • Composer does not seem to be capable of installing folders with a specific ACL set on them — only
    SysObject seem to allow ACL specification.
  • ACLs set on Folders imported from another repository will NOT be preserved when imported into the
    Composer project. You must rely on installation parameters to set ACLs on objects.
  • Installing a BOF module will unlink/unconfigure any previously installed BOF module with the same name
    automatically.
  • Composer logs almost everything it does to a temporary log file in
    %TEMP%/documentum. Each Composer session starts a new log file in this folder, so often the best way to see the most
    recent log is simply to sort the files in the folder by date and look at the most recent one.
  • Often Composer will report an error in the UI, but without much detail. In these cases it can be useful
    to look in the log. The number of misleading errors should be reduced in Composer 6.5.
  • Composer sometimes reports success when in fact there has been an error along the way. It is therefore
    recommended that you always review the log file after any major activity, especially the installation of
    a project into repository.
  • When moving from one version of Composer to another, the recommended approach is to create a new
    workspace, import your Composer projects into that new workspace, and do a clean build.

Conclusion

Composer is a powerful new development platform for building Documentum projects. Although it is still
maturing and may not be right for every project, for those willing to invest some time to understand its
capabilities and limitations, Composer offers a level of flexibility and visibility that until now has not
been possible when building and deploying artifacts into a Documentum repository.

Additional Resources

For additional reading, try the following documentation:

4 Comments

Karthik SR


Hi,

I have read this article and it was very useful… I need some references for DQL queries.

Regards,

SRK



Karthik SR January 8th, 2009 7:38 am

Moo Rad


i have create a code in java to add a child group to a parent group but its not working, any help will be highly appreciated

thanking you in advance
HMM



Moo Rad August 8th, 2012 12:05 am

Abhishek Verma


Hi I am new to Documentum and want to install the Composer to change the description of custom types.

Can anybody let me know where n how to install the composer tool or how to change the description value of custom types?

Thanks,
Abhishek Verma



Abhishek Verma October 9th, 2012 7:58 am

Trackbacks

  1. An introduction to Documentum Composer « Paul Warren