What is Documentum Composer?

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.

Documentum Core Concepts

Artifacts

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.

Projects

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 check-in
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.

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.

Figure 2:
Composer Project Menu

Problems

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.

Figure 3:
Composer Problems Tab

Error Log

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.

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 check-in 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…

Figure 5:
Composer Project Context Menu

Install Documentum Project

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.

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.

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.

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.

Figure 9:
Composer Filters Dialog

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.

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 pre-configured 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.

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 About Documentum Composer

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.

Although 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.

Documentum Composer 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:

• 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
  300006233A01)
• 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