Introduction

One of the key requirements of any agile development methodology is
continuous integrations.
In the 9 years I’ve been writing software professionally, I’ve noticed a dramatic difference in the overall
quality of software produced by projects that employed fully automated continuous integrations over projects
that didn’t. When combined with a full suite of automated integration tests, the benefits of continuous integrations are:

• Immediate detection of broken or incompatible code changes.
• Immediate unit and integration testing of all changes.
• Constant availability of a “current” build for testing, demo, and release purposes.
• Increased efficiency, predictability, and quality of project development cycles.

For releases of Documentum prior to Documentum 6 service pack 1 (D6 sp1), EMC’s only officially
supported mechanism for creating Documentum Business Object Framework modules (BOFs) is through
the Documentum Application Builder (DAB) application, and the only supported mechanism for
installing the DocApp archives generated by DAB is through Documentum Application Installer (DAI).
As of D6 sp1, EMC is shipping a new application, Documentum Composer, that can be used to install
and update BOFs. Of these applications, only Documentum Composer can be executed through a
command-line interface, and none support installing or updating BOFs directly from their Java
archive (JAR) files – you must somehow get the BOF into a repository before you can then create
an archive of the BOF to install into another repository. The net result of this is that there
are no officially supported mechanisms for creating, updating, and/or deploying BOF modules in a
fully automated manner from source code to a target repository.
Thankfully, DAB ships with an Ant task, “BOFPackaging”, that we can use to deploy new modules to a
Documentum repository. With just a basic understanding of both the Apache Ant build tool and the
representation of a module within a repository, using the “BOFPackaging” task is pretty intuitive.
For your reference, I’ve included a
sample project
which demonstrates the BOF installation and
update operations in Ant for Service Based Objects (SBOs), Type Based Objects (TBOs), and simple modules.

Overview of BOF Object Schema and Folder Structure

First I want to provide a brief overview of the structure of BOF modules deployed in a repository.
As of DFC 5.3, Documentum BOF code is stored in the docbase repository and dynamically loaded by
DFC as needed by application code. Service Based Objects (SBOs) are hosted in a single “global”
repository, providing the same functionality to multiple repositories, while Type Based Objects
(TBOs) are hosted and configured in the repository that uses them. Additionally, Documentum introduced
the concept of a “simple module”, which is a unit of executable code stored in the repository. Like
TBOs, simple modules are hosted in the repository that uses them.
To support this new module framework, a few new object types have been introduced: “dmc_module”,
“dmc_java_library”, and “dmc_jar”. “dmc_module” is a subtype of “dm_folder” that represents a BOF module.
Its custom attributes identify the module type, its implementation class, the interfaces it implements,
and the modules it depends on. Other attributes provide version information, a description of the
module’s functionality, the minimum Java VM version the module can run under, and the developer’s
contact information. Please see the Documentum “Content Server Object Reference Guide” for a full description
of the attributes available on the “dmc_module” object type.
A “dmc_module” can contain “dmc_java_library” objects and “dmc_jar” objects. The “dmc_java_library” object
type is also a subtype of “dm_folder” and contains “dmc_jar” objects. The “dmc_jar” object type is a subtype
of “dm_document” and represents Java archive (JAR) files in the repository.
Every repository has a System cabinet, which contains a top level folder named Modules.
By convention, modules are installed under this folder according to their type. For example, SBOs are
installed under “/System/Modules/SBO”, and TBOs are installed under “/System/Modules/TBO”. For simple
modules, you can reuse existing or create additional subfolders of “/System/Modules” that match your
module’s types. For example, if the repository uses Java-based evaluation of validation expressions,
the associated modules would appear under “/System/Modules/Validation”. The hierarchy of folders under
“/System/Modules” is referred to as the repository’s “module registry”, or simply its “registry”.

Figure 1:
Subfolders of Modules representing BOF types.

For more information on the structure of deployed modules, see the “BOF Infrastructure” section of the
Documentum Foundation Classes Development Guide.

Using the “BOFPackaging” Ant Task

As mentioned previously, Documentum’s Documentum Application Builder ships with the “BOFPackaging”
Ant task that we can use to deploy or update modules to a repository. After installing Documentum
Application Builder, you will find the Ant task in the “DDS.jar” file under the
“[Documentum install dir]Shared” directory. Simply add the “DDS.jar” file to your Ant project’s
classpath (“dctm.classpath”), and we’re ready to begin.
First we’ll need to register the custom Ant task using Ant’s taskdef task in an init
target so that we can use it within our Ant script.

<target name="init" >
	<taskdef name="BOFPackaging"
		classname="com.documentum.bof.ant.BOFPackaging"
        classpathref="dctm.classpath" />
</target>

Next we’ll need to create a new Ant target and leverage the “BOFPackaging” task to install
our custom module, which in this example will be a TBO. I’ve included sample SBOs and simple
IDfModules in this article’s sample project as well.

<!-- install TBO -->
<target name="install-tbo" depends="init" description="Installs the document TBO to repository">
	<BOFPackaging contactInfo="steve@argondigital.com"
			description="A Blue Fish document"
			generateWebService="false"
			minVMVersion=""
			moduleName="${tbo.module.name}"
			moduleType="TBO">
		<primaryClass name="com.ArgonDigitalgroup.sample.tbo.impl.CustomDocument" />
		<addToPackage versionPolicy="minor">
			<jarFileSet downloadable="true" file="${tbo.int.jar.file}" jarType="interface" />
			<jarFileSet downloadable="true" file="${tbo.impl.jar.file}" jarType="implementation" />
			<javaLib name="${tbo.module.name} TBO dependencies" sandbox="false">
				<jarFileSet minVMVersion="" downloadable="true" jarType="implementation" dir="${lib.dir}">
					<include name="jdom-1.0b9.jar" />
				</jarFileSet>
			</javaLib>
		</addToPackage>
	</BOFPackaging>
</target>

The following table summarizes the important “BOFPackaging” task attributes and sub-elements that
should be modified to install your own module. For the others values, simply follow the templates
I’ve provided in the sample project.

The following are screenshots of the resulting module as viewed in Webtop.
The module itself resides at “/System/Modules/[module type]/[module name]”,
which in this case is “/System/Modules/TBO/fnd_custom_attr_doc”. The TBO’s
interface and implementation jars are in the module’s root folder:

Figure 2:
TBO interface and implementation JAR files.

The TBO module’s dependencies are stored under the Java library folder
(“dmc_java_library”), “bf_custom_doc TBO dependencies”.

Figure 3:
TBO dependency JAR files.

Conclusion

Using the “BOFPackaging” Ant task, you can easily automate the installation
and update of BOF modules into any repository. This practice will free you
from manual BOF updates, removing what is often the single greatest barrier
to continuous integrations on Documentum projects and resulting in greater
overall efficiency, predictability, and quality of development cycles.

Further Reading

• Article source code – bof_ant_task_samples.zip
• A Practical Guide to the Business Object Framework, by Jason Duke
• Documentum Foundation Classes (DFC) 5.3 Development Guide: Chapter 3 – Using the Business Object Framework (BOF)
• Deploying Modules Outside of a Docapp (EMC Developer Network) – open source Ant task requiring Java 1.5.
• Continuous Integration (Wikipedia)
• Continuous Integration, by Martin Fowler