EMC® Documentum®

Composer

Version 6.5

Quick Start Guide

P/N 300­007­503­A01

EMC Corporation
Corporate Headquarters:
Hopkinton, MA 01748‑9103
1‑508‑435‑1000
www.EMC.com
Copyright © 2008 EMC Corporation. All rights reserved.
Published July 2008
EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice.
THE INFORMATION IN THIS PUBLICATION IS PROVIDED AS IS. EMC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES
OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES
OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Use, copying, and distribution of any EMC software described in this publication requires an applicable software license.
For the most up‑to‑date listing of EMC product names, see EMC Corporation Trademarks on EMC.com.
All other trademarks used herein are the property of their respective owners.
EMC Documentum Technical Document

Table of Contents

What is Composer? ........................................................................................... 3

Workspaces, Artifacts, and DARs ................................................................ 3
UI‑based Composer .................................................................................... 4
Headless Composer .................................................................................... 4
UI‑based Composer or Headless Composer? ................................................ 5

Obtaining, Installing, and Configuring UI­ based Composer ............................. 5

Using Composer ......................................................................................... 6

Obtaining and Installing Headless Composer ................................................... 7

Using Headless Composer .......................................................................... 7
Creating a Build File .................................................................................. 7
Creating a Batch File ................................................................................... 8
Running Ant Tasks ..................................................................................... 9

Installing a DAR File .......................................................................................... 10

What is Composer?
Composer is the next generation development tool for developing, building, and installing
Documentum artifacts which are organized into projects. Most of the DAB/DAI functionality is
available in Composer but there are several fundamental differences in concepts and terminology.
The most important difference is that unlike DAB, Composer does not require a repository
connection in order to view or modify application artifacts. You only need to connect to a
repository when you want to install your projects or import existing objects.
Composer is shipped in two versions, the UI‑based version with wizards, dialogs, and editors,
and a non‑UI command line version that includes a set of Ant tasks for each of the common
Composer functions, such as import, build, and install. The non‑UI version of Composer is also
referred to as headless Composer.

Workspaces, Artifacts, and DARs

Composer is based on the Eclipse Integrated Development Environment (IDE) and thus adopted a
similar terminology to comply with the Eclipse guidelines. Table 1, page 4 describes some of the
new terminology that is used in Composer and relates it to the terminology that was used in DAB.

3 EMC Documentum Composer Version 6.5 Quick Start Guide

EMC Documentum Technical Document

Table 1. Composer/DAB Comparison

Composer Terminology Description DAB Terminology

Artifact A component of an application, such as an Repository object
alias set, lifecycle, or method, packaged
into a project.
Project A project contains the components DocApp
(artifacts) that make up an application. A
project resides on the local machine.
Workspace A directory on the local machine which Repository
contains the project’s artifact files.
A project must be imported into a
workspace before you can build, update,
or install it.

As a best practice you should set up

at least three separate workspaces, as
follows:

• One workspace for UI‑based Composer

projects.
• One workspace for importing
and build projects using headless
Composer.
• One workspace for installing DARs
using headless Composer.
DAR This file is the installable binary file that DocApp Archive
is created by building a project. The file
cannot be modified directly.

UI­based Composer
The Composer GUI should be used for all development tasks, such as developing an application
from scratch or modifying an existing project. You also need to use the Composer GUI for
importing 5.3 DocApps and DocApp archives.
Note: You cannot import a DAR file into Composer. A DAR file is similar to an executable file. It
contains only the binary code and no source files.

Headless Composer
Headless Composer is most useful when you do not want to make any changes to a project but
want to automate compiling an existing project and installing the DAR into a repository.
Note: Headless Composer cannot be used to create new projects or new artifacts.

4 EMC Documentum Composer Version 6.5 Quick Start Guide

 EMC Documentum Technical Document

UI­based Composer or Headless Composer?

Composer is available in two separate packages, Composer and headless Composer. Composer
has a user interface, headless Composer is run from the command line using a batch file and Ant
tasks. Table 2, page 5 describes the main differences.

Table 2. UI­based and Headless Composer Comparison

Features/Functionality UI‑based Composer Headless Composer

Import DocApps from Yes No
repository
Import DocApp archives Yes No
Import project from local Yes Yes
directory
Import Artifact from Yes No
repository
Build project Yes Yes
Install project Yes Yes
Import DAR No No
Install DAR file No Yes

The Composer UI lets you Headless Composer lets you

install the project, a process install a DAR file using the
that includes automatically emc.install Ant task.
generating and installing a
DAR file “behind the scenes”.
However, there is no separate
“Install DAR File” option in
the Composer UI.

Obtaining, Installing, and Configuring

UI­ based Composer
Composer is delivered in the form of a compressed .Zip file that contains the Eclipse platform
and all required plug‑ins.
To set up UI‑based Composer:
• Download Composer package and extract the package to a local directory.
• Download and install Java JDK 1.5 (if it is not already installed on your local machine).
• Set JAVA_HOME environment variable to point to Java JDK 1.5.
• Configure the connection broker.
• Start Composer and create a workspace.

EMC Documentum Composer Version 6.5 Quick Start Guide 5

EMC Documentum Technical Document

For more detailed information on how to install and configure Composer, see Chapter 1 in the
Composer User Guide.

Using Composer
After you have installed Composer, you are ready to work on Documentum projects. You can
create a project from scratch, migrate a 5.3 DocApp or DocApp archive into Composer, or import
an existing project from a local directory. Figure 1, page 6 describes a typical workflow in
Composer.

Figure 1. Composer Workflow

Table 3, page 6 describes the most common Composer tasks.

Table 3. Composer Tasks

Task Steps User Guide Topic

Create a project from Select File > New > Project > Chapter 2, “Creating a new
scratch Documentum Project > Documentum project”
Project
Add artifacts to • Expand Artifacts folder in project. Chapter 2, “Adding or
project selecting artifacts”
• Right‑click associated artifact folder,
select New > Other and select artifact
from list
Import artifact from Select File > Import > Documentum > Chapter 2, “Importing
repository into Artifacts From Repository artifacts”
project
Import an existing Select File > Import > Documentum > Chapter 2, “Importing a
project from local External Projects Into Workspace project”
directory
Migrate a DocApp Select File > New > Project Chapter 3, “Migrating a
> Documentum Project > New repository DocApp”
Documentum Project from DocApp
Migrate a DocApp Select File > New > Project > Chapter 3, “Migrating a
archive Documentum Project > Documentum DocApp archive”
Project from Local DocApp Archive

6 EMC Documentum Composer Version 6.5 Quick Start Guide

 EMC Documentum Technical Document

Obtaining and Installing Headless

Composer
Headless Composer is delivered in the form of a compressed .Zip file that contains headless
Eclipse and all required plug‑ins.
To set up headless Composer:
• Download headless Composer package for your platform and extract the
package to a local directory. The headless Composer package has the format
DCTM_Headless_Composer_<platform>_<version>.zip. When you extract headless
Composer, do not extract it to a directory name that contains spaces. If the headless Composer
directory path contains any spaces, Ant tasks do not run correctly.
• Configure the connection broker.
• Create at least two separate workspaces, one for importing and building project, and one for
installing DAR files into a repository.

Using Headless Composer

After you have installed headless Composer, you need to create your build and batch files to run
Ant tasks. Figure 2, page 7 describes a typical workflow when using headless Composer.

Figure 2. Headless Composer Workflow

In your build scripts and batch file you should:

• Create a clean build workspace.
• Copy the projects into the build workspace.
• Import projects into the clean build workspace by calling the emc.importProject Ant task.
• Build projects and create DAR by calling emc.build and emc.dar Ant tasks.
• Create a clean install workspace.
• Install the DAR file using the previous build process by calling the emc.install Ant task.

Creating a Build File

The build file calls the Ant task you want to execute. The build file must be in XML format. Table
4, page 8 describes the Ant task that are supported by headless Composer.
For more information about parameters and syntax, see the Chapter 20 in the Composer User Guide.

EMC Documentum Composer Version 6.5 Quick Start Guide 7

EMC Documentum Technical Document

For detailed example on how to use headless Composer to install a DAR file, see Installing
a DAR File, page 10.

Table 4. Headless Composer Ant Tasks

Ant Task XML Code Description

emc. Imports a project into the
<emc.importProject
importProject workspace.
dmproject="project"
failonerror="true/false" />

emc.build Compiles an existing

<emc.build
Composer project.
dmproject="project"
failonerror="true/false" /> The project should be
compiled in a clean
workspace.

emc.dar Generates a DAR file

<emc.dar
from an existing project.
dmproject="project"
manifest="bin/dar/project.dardef.
artifact"
dar="c:/project.dar" />

emc.install Installs a DAR file into a

<emc.install
repository.
dar="C:/project.dar"
docbase="repository"
username="name"
password="password"
domain="" />

Creating a Batch File

The batch file sets up the environment variables and passes the build file, as described in Table
5, page 8 .
For a detailed example batch file, see Installing a DAR File, page 10.

Table 5. Batch File

Code Description

echo off setlocal

Specifies the location of headless
set ECLIPSE="C:\<..>\ComposerHeadless"
Composer. The directory name
should not contain any spaces.

8 EMC Documentum Composer Version 6.5 Quick Start Guide

 EMC Documentum Technical Document

Code Description
Specifies the workspace that is
set BUILDWORKSPACE="c:\<..>\
used when a project is build.
ComposerHeadless\<build_workspace>"
Specifies the path and the name
set BUILDFILE="R:\<path>\<buildfile>.xml"
of the build file that contains the
required parameters for building
a project.
Specifies the path and the name of
set INSTALLFILE="R:\<path>\<installfile>.xml"
the file that contains the required
parameters for installing a DAR
file.
Specifies the directory where the
set DARPROJECTSDIR="R:\<path>\<directory>"
generated DAR file is stored.
Specifies the workspace that is
set INSTALLWORKSPACE="c:\<..
used when a DAR file is installed.
>\ComposerHeadless\
<install_workspace>"
Removes all directories and files in
rmdir /S /Q %BUILDWORKSPACE%
the build and install workspaces
rmdir /S /Q %INSTALLWORKSPACE%
and copies the project files into
xcopy %DARPROJECTSDIR% %BUILDWORKSPACE% /E /I
the build workspace and DAR file
into the install workspace.
Sets the Java parameters for the
java ­cp %ECLIPSE%\startup.jar org.eclipse.
build workspace and build file.
core.launcher.Main
All parameters must be entered
­data %BUILDWORKSPACE%
on the same line without any line
­application org.eclipse.ant.core.antRunner
breaks.
­buildfile %BUILDFILE%
Sets the Java parameters for
java ­cp %ECLIPSE%\startup.jar org.eclipse.
the installation workspace and
core.launcher.Main
installation file. All parameters
­data %INSTALLWORKSPACE%
must be entered on the same line
­application org.eclipse.ant.core.antRunner
without any line breaks.
­buildfile %INSTALLFILE%

Running Ant Tasks

After you have created your batch and build file, you can run the Ant tasks, as follows:
C:\><..>\ComposerHeadless <batch file>.bat <build file>.xml

Where <batch file> is the name of the batch file and <build file> is the name of the build file.

EMC Documentum Composer Version 6.5 Quick Start Guide 9

EMC Documentum Technical Document

Installing a DAR File

One of the most common tasks for headless Composer is to import a project, build it, and then
install the DAR file into a repository. The following procedure describes this process and contains
example code for the associated build and batch files.

To install a DAR file:

1. Create the build file that imports the project, builds the project, and generates the DAR file
using the emc.importProject, emc.build, and emc.dar Ant tasks.
The following DARBuild.xml example build file contains the code to import and build the
SmartContainer project, and to generate the SmartContainer.dar.

<?xml version="1.0"?>
<project
name="build­smart­container" XML declarations and tags.
default="build">
<target name="build">
Imports the
<emc.importProject
SmartContainer project.
dmproject="SmartContainer"
failonerror="true"/> The failonerror parameter
specifies that the import
fails if any errors are
encountered during the
import process.

Builds the SmartContainer

<emc.build
project.
dmproject="SmartContainer"
failonerror="true"/> The failonerror parameter
specifies that the build
fails if any errors are
encountered during the
build process.

Generates the
<emc.dar
SmartContainer.dar file
dmproject="SmartContainer"
from the SmartContainer
manifest="bin/dar/
project.
smartcontainer.dardef.artifact"
dar="c:/ComposerHeadless/ The manifest parameter
build_workspace/SmartContainer/ specifies the location of
SmartContainer.dar"/> the manifest file, which
contains the packaging
instructions for the DAR
file.

The dar parameter specifies

the location where

10 EMC Documentum Composer Version 6.5 Quick Start Guide

 EMC Documentum Technical Document

generated the .dar file

is stored.

</target> XML closing tags.

</project>

2. Create the build file that installs the DAR file into the repository.
The following example DARInstall.xml build file contains the code to install the
SmartContainer.dar.

<?xml version="1.0"?>
<project name="install­smart­container" XML declarations and tags.
default="install">
<target name="install">

<emc.install
dar="c:/ComposerHeadless/build_workspace/
SmartContainer/SmartContainer.dar" Installs the SmartCon‑
docbase="repo1" tainer.dar file in the repo1
username="user" repository.
password="aabbcc"
domain="" />

</target> XML closing tags.

</project>

3. Create the batch file that calls both build files.

The following SmartContainerBuild.bat file sets up the environment variables, workspaces,
and DARBuild.xml and DARInstall.xml files.

echo off setlocal

Sets the headless
set ECLIPSE="C:\ComposerHeadless"
Composer workspace.
Sets the workspace that is
set BUILDWORKSPACE="C:\ComposerHeadless\
used when building the
build_workspace"
project.

Sets the build file that

set BUILDFILE="R:\Smart_Container\Main\buildEnv\
is used for building the
DARBuild.xml"
project.
Sets the installation
set INSTALLFILE="R:\Smart_Container\Main\
build file that is used
buildEnv\DARInstall.xml"
for installing the DAR file.

EMC Documentum Composer Version 6.5 Quick Start Guide 11

EMC Documentum Technical Document

Sets the DAR file location

set DARPROJECTSDIR="R:\Smart_Container\Main\
directory. This is where
darProjects"
the DAR file is stored
when it is generated.
Sets the workspace
set INSTALLWORKSPACE="C:\ComposerHeadless\
that is used during the
install_workspace"
installation process.
Cleans the build
rmdir /S /Q %BUILDWORKSPACE%
workspace and install
rmdir /S /Q %INSTALLWORKSPACE%
workspace, and copies
xcopy %DARPROJECTSDIR% %BUILDWORKSPACE% /E /I
the content from the DAR
file directory to the build
workspace.
Sets the Java parameters
java ­cp %ECLIPSE%\startup.jar org.eclipse.
for building the project
core.launcher.Main
and generating the DAR
­data %BUILDWORKSPACE%
file.
­application org.eclipse.ant.core.antRunner
­buildfile %BUILDFILE%
Set the Java parameters for
java ­cp %ECLIPSE%\startup.jar org.eclipse.
installing the DAR file.
core.launcher.Main
­data %INSTALLWORKSPACE%
­application org.eclipse.ant.core.antRunner
­buildfile %INSTALLFILE%

4. Build the project and generate the DAR file by running the Ant task, as follows:
C:\ComposerHeadless> SmartContainerBuild.bat DARBuild.xml

5. Install the DAR file by running the Ant task, as follows:

C:\ComposerHeadless> SmartContainerBuild.bat DARInstall.xml

12 EMC Documentum Composer Version 6.5 Quick Start Guide