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:
- 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
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.
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.
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.
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.
Files and File Types
There are a variety of files and file types that make up a Composer project.
- Eclipse project files (
- Composer project files (
- Artifact XML source files (
*.type, and so forth)
- Installation Parameter definition files (
- Content files (
- DAR Definition file (
- Compiled artifact files (
- Compiled DAR file (
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.
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.
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.
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:
- Alias Sets
- Aspect Modules
- Aspect Types
- Installation Parameters
- Jar Definitions
- Java Libraries
- Permission Sets
- Relation 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.
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
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.
This attribute can be found within the URL specified by the href attribute of the
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!
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.
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.
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
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.
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,
- 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
- 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.
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:
- EMC® Documentum® Composer Version 6.0 SP1.5 User Guide (P/N 300005253A02)
- EMC® Documentum® Composer Version 6.0 SP1.5 Release Notes (P/N 300006232A02)
- EMC® Documentum® Composer Version 6.0 SP1 Plugin Developer Guide (P/N 300006231A01)
- EMC® Documentum® Composer Version 6.0 SP1 Language Pack Installation and Release Notes (P/N
Creating DFS Services Using Documentum Composer
(from Paul Warren’s blog)
Documentum Composer: Integrating BOF Development into your workflow
(from Paul Warren’s blog)
Installing Documentum Composer on the Web Tools Project
(from Paul Warren’s blog)
Items tagged with ‘Composer’
within the Documentum community on EDN