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.
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.
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.
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:
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
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.
It is strongly recommended to keep your Composer workspace separate from any other Eclipse workspaces that
may already exist.
In order to make it possible to drive certain installation behavior based on parameters entered at the time
of installation, Composer utilizes
. 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.
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.
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.
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
eclipse.exe executable automatically launches Composer.
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.
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.
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.
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.
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…
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.
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.
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.
There are a variety of files and file types that make up a Composer project.
*.type, and so forth)
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
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
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.
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
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.
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.
The Navigator pane shown below has had all filters disabled, revealing all hidden projects, folders, and
folder contains the XML artifact “source files” from which your Composer project is built.
folder contains the binary and other content files used to back artifacts that require content, such as
documents. The folder structure within the
folder is created automatically by Composer as content is imported into the project from repositories and
the local file system. The
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”
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.
folder contains XML source required by the project as a whole, including an object type definition and
default installation settings for the project.
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.
/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.
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:
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.
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.
The list below provides an overview of some of the key XML elements and attributes you may need to work
<dataModel>element within an artifact’s XML, typically a
<sysObject>element references to the artifact in the corresponding
<Artifact:Artifact>element. It is a unique identifier which has no purpose other than to uniquely
<contentStore.contentEntries.value>element specifies the path within the
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.
For more details concerning DocApp migration, consult the
Migrating a repository DocApp
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.
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.
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,
%TEMP%/documentum. Each Composer session starts a new log file in this folder, so often the best way to see the most
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.
For additional reading, try the following documentation: