Automate BOF Module Deployment During Development

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

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@bluefishgroup.com"
			description="A Blue Fish document"
			generateWebService="false"
			minVMVersion=""
			moduleName="${tbo.module.name}"
			moduleType="TBO">
		<primaryClass name="com.bluefishgroup.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.

Attribute / Element	TBO	SBO	IDfModule
moduleName (attribute)	The TBO’s object type. For example, bf_document	The SBO’s fully qualified interface name. For example, com.bluefishgroup.ICustomService	Any unique module name.
moduleType (attribute)	TBO	SBO	Any appropriate type name. For example, Aspect, Lifecycle, Validation, or “” (empty String)
primaryClass (element)	The implementation class	The implementation class	The implementation class
jarFileSet (element; jarType=interface)	The jar file which contains the interface classes. (Optional)	The jar file which contains the interface classes.	The jar file which contains the interface classes. (Optional)
jarFileSet (element; jarType=implementation)	The jar file which contains the implementation classes	The jar file which contains the implementation classes	The jar file which contains the implementation classes
javaLib (element)	Includes all third party dependencies. (Optional)	Includes all third party dependencies. (Optional)	Includes all third party dependencies. (Optional)

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:

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

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