OpenText™ Documentum® D2

Version 4.7

Developers Guide

Open Text Corporation

275 Frank Tompa Drive
Waterloo, Ontario, Canada
N2L 0A1
www.opentext.com
Legal Notice

This documentation has been created for software version 4.7.

It is also valid for subsequent software versions as long as no new document version is published.

Open Text Corporation

275 Frank Tompa Drive, Waterloo, Ontario, Canada, N2L 0A1

Tel: +1-519-888-7111
Toll Free Canada/USA: 1-800-499-6544 International: +800-4996-5440
Fax: +1-519-888-0677
For more information, visit https://www.opentext.com

Copyright 2017 Open Text. All Rights Reserved. Trademarks

owned by Open Text.

Adobe and Adobe PDF Library are trademarks or registered trademarks of Adobe Systems Inc. in the U.S. and other countries.

Disclaimer

No Warranties and Limitation of Liability

Every effort has been made to ensure the accuracy of the features and techniques presented in this publication. However, Open Text
Corporation and its affiliates accept no responsibility and offer no warranty whether expressed or implied, for the accuracy of this
publication.

OpenText™ Documentum® D2 Version 4.7 User Guide 3

Contents
Developers Guide ................................................................................................................................ 1
Intended audience ............................................................................................................................................... 5
Extending D2 ........................................................................................................................................ 7
Introduction to Extending D2 ............................................................................................................. 7
Migrating to Use the Content Checkin Service ................................................................................. 9
Content Checkin Service .................................................................................................................... 9
Understanding D2 Architecture......................................................................................................... 11
Understanding the D2 Client Architecture ....................................................................................... 11
Application Server Layer (D2.war) ..................................................................................................................... 12
Content Server Layer ........................................................................................................................................ 12
Understanding the D2 Config Architecture ..................................................................................... 13
Browser Layer ................................................................................................................................................... 13
Application Server Layer (D2-Config.war) .......................................................................................................... 14
Content Server Layer ........................................................................................................................................ 14
Understanding D2 File Transfer........................................................................................................ 14
Building Integrations Using D2FS..................................................................................................... 17
Using SOAP to Allow External Applications to Affect D2 Processes and Data ..........................17
Generating Java Stub Libraries to Call D2FS Using SOAP ..........................................................17
D2FS Examples.................................................................................................................................. 18
Setting Up the D2FS Examples ........................................................................................................ 18
Using OAH to Create and Configure a Sample External Widget ...................................................19
Understanding Open Ajax Hub (OAH) and External Widgets ......................................................19
Setting Up the Sample External Widget ........................................................................................... 19
Walking Through the Sample External Widget .............................................................................. 20
Importing OAH Scripts ...................................................................................................................................... 20
Creating and Connecting an Open Ajax Hub .................................................................................................... 21
Subscribing to Events ....................................................................................................................................... 21
Sending Messages ........................................................................................................................................... 22
Understanding Audit Events ............................................................................................................. 24
Understanding Documentum D2 Auditable Events ....................................................................... 24
Adding a Human Readable Label to the Audit Event .................................................................... 25
Adding an Extended Label to the Audit Event ............................................................................... 25
Creating an Audit Event at Code Level ........................................................................................... 27
Creating and Configuring a Custom Plug-in .................................................................................. 31
Understanding Custom Plug-ins ...................................................................................................... 31
Overview of the Template Plug-in Examples ................................................................................... 32
Customizing Content Export .............................................................................................................................. 32
Overriding a Service with Post-Processing ....................................................................................................... 32
Overriding a Service with Pre-Processing.......................................................................................................... 32
Downloading and Setting Up the Template Plug-in ...................................................................... 32
Building, Installing, and Verifying the Template Plug-in .............................................................. 34
Configuring a Menu Item for the Template Plug-in ....................................................................... 34
Creating a New Plug-in Using the Template ................................................................................... 35
Configuring a Custom Action ........................................................................................................... 35
Understanding Service Interface Overrides ................................................................................... 36
Pre-Processing ................................................................................................................................................. 36
Post-Processing ................................................................................................................................................ 36
Overriding the Process ...................................................................................................................................... 37
Throwing Exceptions ......................................................................................................................................... 38
Setting Up D2 Service Overrides ..................................................................................................... 39
Deploying D2 Plug-ins ...................................................................................................................... 40
Create a Custom Dialog .................................................................................................................... 40
Deploying Custom Dialog ................................................................................................................ 42
Open Custom Dialog from a Menu .................................................................................................. 42
Extending C2 PDF functionality ....................................................................................................... 42

OpenText™ Documentum® D2 Version 4.7 User Guide 5

 Preface
OpenText® Documentum® D2 consists of two components:

• D2 Configuration: It is a web-based application, hereafter known as D2 Config, for

administrators to use to configure settings such as automated content-handling
processes and background settings for D2 Client.

• D2 Client: It is a web-based application, hereafter known as D2 Client, for users to

interact with content in one or more repositories.
When this guide refers to D2, it refers to the product as a whole and not the individual components.

Intended audience
The information in this guide is for developers who create and configure extensions for D2, using the D2
and D2 Foundation Services (D2FS) API.

OpenText™ Documentum® D2 Version 4.7 User 5

 Chapter 1

Extending D2
This chapter contains the following topics:

• Introduction to Extending D2

Introduction to Extending D2
Before customizing D2 by using extensions, you must carefully re-examine the functionalities available
through D2 and its official plug-ins. In almost all cases, using existing capabilities to achieve your use
cases provides a less expensive and more reliable solution.
D2 offers the following methods of extending D2 by using the D2 API:
• Building integrated solutions by using the D2FS services to interact with the D2 web
application.
• Using Open Ajax Hub (OAH) and Javascript to create external web applications that
can be manipulated as iframes (External Widgets) from within the D2 web
application.
• Using D2 Java packages to create and configure D2 plug-ins that add custom actions
or override existing D2 services.
You can use any Integrated Development Environment (IDE), such as Eclipse, for building the code.

OpenText™ Documentum® D2 Version 4.7 User 7

 Chapter 2
Migrating to Use the Content Checkin
Service
This chapter contains the following topics:

• Content Checkin Service

Content Checkin Service

For D2 4.2 and later releases, the content checkin process uses
IDownloadService.getCheckinUrls()service to perform the checkin operation as a single,
atomic operation.
To use this checkin process for D2 4.1 release, cease the usage of the checkin() and
getUploadUrls() services and use the getCheckinUrls()service. You can continue to use the
checkin() service for content-less objects and the getUploadUrls()method for non-checkin
operations.
OpenText Documentum D2 D2FS API JavaDoc contains further information on
getCheckinUrls()and its required attributes.

OpenText™ Documentum® D2 Version 4.7 User 9

 Chapter 3

Understanding D2 Architecture
This chapter contains the following topics:

• Understanding the D2 Client Architecture

• Understanding the D2 Config Architecture
• Understanding D2 File Transfer
Understanding the D2 Client Architecture
D2 Client consists of three layers:
• The Browser layer denoting the web browsers that are used by end users to connect to
D2.
• The web application server layer that corresponds to the installation and configuration
of D2.war.
• The Documentum Content Server layer that consists of the installed DAR files.
The following graphic illustrates the composition and relationship between the three layers:

OpenText™ Documentum® D2 Version 4.7 User 11

Understanding D2 Architecture

Browser Layer
D2 Client is a Web 2.0 browser-based application. End users can navigate to the D2 Client web application
URL to log in to use D2. D2 Client is:
• GWT/GXT-based: D2 Client uses Sencha GXT and the Google Web Toolkit (GWT) to
manage JavaScript. As a result, the D2 Client JavaScript code is delivered hidden and in a
single large file. You cannot extend or debug D2 Client without the original source.
• The Sencha website (http://www.sencha.com/products/gxt) contains further information on
GXT.
• Loaded onto a single HTML page: D2 Client interprets and loads JavaScript into the browser
memory at the start. As a result, D2 manipulates HTML DOM to remove and replace
interface portions rather than switching the HTML pages upon user navigation.
• GWT RPC-based: D2 uses standard HTTP requests for all communication between the
browser client and the D2 web application. For requests for static resources such as images,
D2 uses GWT RPC calls backed by the D2FS services layer, to retrieve dynamic data.
The Google developer site (https://developers.google.com/) has more information on GWT RPC.

Application Server Layer (D2.war)

D2 Client is packaged as a .war file that can be deployed on most J2EE application servers. The web
application server consists of:
• The D2 web application: Includes most of the presentation logic, including the GWT and
GXT libraries, custom interface controls, static web resources, and pass-through services to
allow web browsers to invoke the D2FS services. The layer does not link to the Documentum
• Foundation Classes (DFC) or Documentum Foundation Services (DFS) client libraries
because all communication between the D2 web application and the Documentum repository
passes through the D2FS interface.
• The D2FS library: Contains all D2 business logic, including the communication between the
Documentum Content Server through DFC and DFS, the logic for interpreting and applying
D2 configurations to service requests, and a set of SOAP services.
The application server layer uses the D2FS Java API while allowing external clients to use the SOAP interface
because D2FS is merged with D2. Plug-ins to D2 exist in the D2FS layer and can intercept existing calls to the
D2FS interface to change or enhance D2 behaviors.

Content Server Layer

The D2 installation includes three DAR files:
• D2–DAR.dar: Includes most of the Documentum types necessary for storing configuration
objects in the repository. Configuration objects are subtypes of d2_module_config or
d2_moduledoc_config, depending on whether the configuration is stored as object metadata
or as XML content. D2 favors XML for representing forms, dialog boxes, mail templates, and
other structured content, where a set of repeating attributes is insufficient for representing a
configuration.
• D2 DAR includes jobs and methods that are used by D2 for implementing some D2
configurations. These methods are invoked by a scheduled job for completing the background
tasks, or are invoked by the D2 web application in response to events. OpenText Documentum
D2 Administrator Guide contains further information about D2 jobs and methods.
12 OpenText™ Documentum® D2 Version 4.7 User Guide
 Understanding D2 Architecture
• D2–Widget-DAR.dar: Includes configuration types related to the D2 4.x interface, such as
widgets, workspace layouts, and themes.
• Collaboration_Services.dar: Includes types and Documentum Business Object
Framework modules for Documentum collaboration capabilities. D2 requires this DAR file to
enable commenting within D2 Client.

Understanding the D2 Config Architecture

D2 Config copmprises three layers:
• The Browser layer denoting the web browsers used by end users to connect to D2 Config.
• The web application server layer that corresponds to the installation and configuration of D2–
Config.war and the D2-Widget plug-in.

• The Documentum Content Server layer.

The following graphic illustrates the composition and relationship between the three layers:

Browser Layer
D2 Config is a Web 2.0 browser-based application. End users can navigate to the D2 Config web application
URL to log in to use D2. D2 Config is:
• ActiveX control-based: D2 Config uses the ActiveX control such as the old D2 3.x
architecture and is accessible only by using the Microsoft Internet Explorer browsers.
• XML-based: D2 Config uses the old D2 3.x architecture for D2 and delivers the interface to
the web browser in XML representation.

OpenText™ Documentum® D2 Version 4.7 User 13

Understanding D2 Architecture

Application Server Layer (D2-Config.war)

D2 Config is packaged as a .war file that can be deployed on most J2EE application servers. The web
application server consists of the following:
• D2 Config web application: Includes most of the presentation logic, including the ActiveX
controls. The layer includes the Documentum Foundation Classes (DFC) or the Documentum
Foundation Services (DFS) client libraries because the layer controls communication between
the D2 Config web application and the Documentum repository.
• D2-Widget plug-in: Adds the configuration components for D2 Client to D2 Config.

Content Server Layer

D2 installation includes three DAR files:
• D2–DAR.dar: Includes most of the Documentum types necessary for storing configuration
objects in the repository. Configuration objects are subtypes of d2_module_config or
d2_moduledoc_config depending on whether the configuration is stored as object metadata
or as XML content. D2 uses XML for representing forms, dialog boxes, mail templates, and
other structured content, where a set of repeating attributes is insufficient for representing a
configuration.
D2 DAR includes jobs and methods that are used by D2 for implementing some D2
configurations. These methods are invoked by a scheduled job for completing the background
tasks, or are invoked by the D2 web application in response to events. OpenText Documentum
D2 Administrator Guide contains further information about D2 jobs and methods.
• D2–Widget-DAR.dar: Includes configuration types related to the D2 4.x interface, such as
widgets, workspace layouts, and themes.
• Collaboration_Services.dar: Includes types and Documentum Business Object
Framework modules for Documentum collaboration capabilities. D2 requires this DAR file to
enable commenting within D2 Client.

Understanding D2 File Transfer

D2 uses either the D2 Java applet or HTML5 (thin client mode) to perform content transfer, giving it several
advantages over the standard HTML4 <fileinput> form control:
• Multiple-file upload.
• Upload of entire folder structures.
• Drag-and-drop of files from the desktop for upload.
• Client-side compression of content before the upload.
Browsers that support HTML5 can run D2 without the Java applet in thin client mode but do so with limited
functionality. OpenText Documentum D2 Installation Guide contains information about the functionalities that
are restricted by the thin client mode and the instructions for setting the file transfer mode.
The following graphic illustrates the data flow of content transfer between Documentum Content Server and the
D2 web applications:

14 OpenText™ Documentum® D2 Version 4.7 User Guide

 Understanding D2 Architecture

In basic installations, with most users in close geographic proximity, the D2 applet uses a standard HTTP
connection to connect directly to the D2 web application.
Use the Documentum Branch Office Caching Services (BOCS) cache to speed up the transfer of large files to
users in remote locations. You must install the D2-BOCS plug-in on the same server as the BOCS cache to:
• Facilitate communication between the D2 applet and the BOCS cache.
• Allow D2 to manipulate content in and out of the repository. For example, the C2 plug-in can
be used to insert configuration-based watermarks.
D2-BOCS must apply configuration rules to complete the C2 and the O2 content operations. As a result, D2-
BOCS opens a DFC session with the repository, which makes Documentum RPC calls to the repository to
retrieve configuration objects and content metadata. Due to the relatively high latency of the connection between
the BOCS cache and Content Server, administrators and end users must limit the number of applicable O2 and
C2 configurations. Configure D2 so that only large files are transferred using the BOCS cache to reduce load on
the connection and to connect directly to the D2 application for the transfer of smaller files.

OpenText™ Documentum® D2 Version 4.7 User 15

 Chapter 4

Building Integrations Using D2FS

This chapter contains the following topics:

• Using SOAP to Allow External Applications to Affect D2 Processes and Data

• Generating Java Stub Libraries to Call D2FS Using SOAP
• D2FS Examples
• Setting Up the D2FS Examples

Using SOAP to Allow External Applications to

Affect D2 Processes and Data
The D2FS API is exposed from the D2 web application as a set of SOAP services. Generating Java
Stub Libraries to Call D2FS Via SOAP contains instructions for generating the Java stub libraries that
are required to invoke D2FS byusing SOAP services.
The D2 SDK package contains the sample Java classes that use the Java stub libraries to invoke and
modify the D2 processes and data.
OpenText Documentum D2 D2FS API JavaDoc contains further information on the available
D2FS services.

Generating Java Stub Libraries to Call D2FS

Using SOAP
1. Deploy D2 to a local application server.

2. Use the following command to generate the Java source files for the stub libraries that
are needed to connect to D2:
wsimport —keep http://localhost:8080/D2/ws/d2fs.wsdl

The -keep parameter saves the files so that you can copy them to your project.

3. If you have generated stubs by using a different D2 server than the one you have used to
call D2FS, modify the URL. to do this, open ModelPortService.java and edit
the following line:
static { url = new URL("http://<D2 server address and
port>/D2/ws/d2fs.wsdl"); }

OpenText™ Documentum® D2 Version 4.7 User 17

Building Integrations Using D2FS

D2FS Examples
Navigate to the D2FS/Java/D2FSExamples/src/com/OpenText/d2/d2fs/examples folder in
the D2 SDK package for the following examples of Java classes:
Class Description
ContextAndLoginExample.java Demonstrates how to establish a D2FS login context
with the D2 server.
ImportAndUploadDocumentExample.java Demonstrates how to use createproperties()
to import and upload content.
DestroyExample.java Demonstrates how to destroy content.
SavePropertiesExample.java Demonstrates how to set content attributes.
SearchQuickExample.java Demonstrates how to run a quick search.
SearchAdvancedExample.java Demonstrates how to:
• Use SearchService and ContentService to search
the repository.
• Save or run an advanced search.
• List saved searches.
• Run a saved search.
CheckinContentExample.java Demonstrates how to use getCheckinUrls() to :
• Check out content.
• Request a checkin URL.
• Post new content with checkin parameters.
TaxonomyEnumAndExportUrlExample.java Demonstrates how to use ContentService to:
• Enumerate taxonomy objects.
• Download and save the exported taxonomy.

Setting Up the D2FS Examples contains instructions for setting up the D2FS examples after you
generate the Java stub libraries.

Setting Up the D2FS Examples

1. Use Eclipse to create a new workspace, and then import the existing projects into the
workspace from the D2FS/Java/D2FSExamples folder.

2. Delete the com.emc.d2fs.* and org.w3.* packages if they are available in the
project.

3. Copy the generated com and org folders to your project.

You can paste the folders directly from the local file directory to the src/ folder of your IDE.

4. Update LoginInfo.java to specify the repository name, login ID, password, and
URL of the web application.

5. Check the setup comments available above the example, to confirm the required inputs.

18 OpenText™ Documentum® D2 Version 4.7 User Guide

 Chapter 5
Using OAH to Create and Configure a
Sample External Widget
This chapter contains the following topics:

• Understanding Open Ajax Hub (OAH) and External Widgets

• Setting Up the Sample External Widget
• Walking Through the Sample External Widget

Understanding Open Ajax Hub (OAH) and

External Widgets
Open Ajax Hub (OAH) is a standard JavaScript library for publishing and subscribing to web
applications and is defined by OpenAjax Alliance to address interoperability and security issues that
arise when multiple Ajax libraries and components are used in the same web page. You can use OAH
to:
• Publish to a channel to send a message.
• Subscribe to a channel to listen for a message.
A D2 external widget is a web application URL that is hosted in an iframe within the D2 Client
application. D2 uses OAH to communicate between widgets and to broadcast events and actions such as
content selection, object location, and content view.
• Events notify listeners about the D2 application and widget-specific attributes.
• Actions cause D2 or widgets to perform a specified operation.
The D2 implementation of OAH, called D2-OAH.js, provides the binding between a web page and the
surrounding D2 application. D2 Config refers to these web pages as external widgets, which are hosted
in an iframe within the D2 Client web application.
The X3PubSubEvents section of OpenText Documentum D2 Open Ajax Hub (OAH) Event and Actions
JavaDoc contains a complete reference of the OAH message objects, the D2-OAH API, and the list of
available actions and events.
Note: The D2 actions and events not covered by the SDK are not available.

Setting Up the Sample External Widget

1. Extract UpdateDocList folder from D2 <version> SDK.zip to a temporary
location.

2. Stop the web application server.

3. Copy the X3–Ext-UpdateDoclist folder to the <web application
server>/webapps/ folder.

OpenText™ Documentum® D2 Version 4.7 User 19

Using OAH to Create and Configure a Sample External Widget

4. Start the web application server.

5. Log in to D2 Config:
a. Navigate to File > Import configuration from the menu bar.

b. Import X3–Ext-UpdateDoclist — Config.zip

OpenText Documentum D2 Administration Guide contains further instructions on importing
configurations.
c. Navigate to Widget view > Widget from the menu bar.

d. Select the WG EXT UpdateDoclistwidget.

e. Modify the Widget url field to match the location of the web application server that you have
deployed. For example: http://myserver:8080/X3–Ext-UpdateDoclist
The sample external widget also contains a second URL that displays an Open Ajax Hub publish and subscribe
application: http://myserver:8080/X3–Ext-UpdateDoclist/devindex.html

6. Log in to D2 Client and add the new widget to your workspace.

Walking Through the Sample External Widget

The X3–Ext-UpdateDoclist sample external widget shows how to:
• Create a D2OpenAjaxHub object to connect the external widget to D2.
• Use the Open Ajax Message Hub to execute a query form and to update the doclist widget.
• Use the Open Ajax Hub to subscribe to the D2 events and to receive messages.
Open X3–Ext-UpdateDoclist/index.html in a text editor to view the sample code.
The X3PubSubEvents section of OpenText Documentum D2 Open Ajax Hub (OAH) Event and
Actions JavaDoc contains a complete reference to the Open Ajax Hub (OAH) classes and methods as
well as a complete list of D2 events, actions, and their corresponding attributes.
Importing OAH Scripts
You must import the following two Javascript scripts:
• Use one of the following:
http://YourServer:8080/D2/container/OpenAjaxManagedHub-all-obf.js

http://YourServer:8080/D2/container/external-api/OpenAjaxManagedHub-all.js
OpenAjaxManagedHub-all-obf.jsis the smaller version that is used by D2 for production purposes and
OpenAjaxManagedHub-all.jsis the full version that is used for development purposes.

http://YourServer:8080/D2/container/external-api/D2-OAH.js

20 OpenText™ Documentum® D2 Version 4.7 User Guide

 Using OAH to Create and Configure a Sample External Widget

Creating and Connecting an Open Ajax Hub

Create and connect a D2OpenAjaxHub() object. The sample code uses the following code:
var d2OpenAjaxHub = new D2OpenAjaxHub();
// connect hub providing callback functions.
d2OpenAjaxHub.connectHub(connectCompleted, onInitWidget, onActiveWidget,
onDisplayWidget);

You can then set a callback for a successful connection to the hub to perform initialization tasks. For example, the
sample waits for the hub client to connect, and then initiates the subscription to events.
function connectCompleted(hubClient, success, error) {
if (success) {

logit("Hub client connected");

// subscribe to events
subscribeEvents();

} else
logit("Hub client NOT connected - please check console");
}

The sample widget always subscribes to events even if you do not request that the widget track and display objects of
the selected type.
// onInitWidget is called to allow widget initialization (can subscribe or //
initialize as needed)
// message contains an OpenAjaxMessage() object
function onInitWidget(message) {
logit("onInitWidget()");
}

// onActiveWidget is called when the external widget is activated or

//deactivated.
function onActiveWidget(bActiveFlag) {
logit("onActiveWidget(): bActiveFlag=" + bActiveFlag);
}

// onDisplayWidget is called with the external widget is displayed or

//hidden.
function onDisplayWidget(bDisplay) {
logit("onDisplayWidget(): bDisplay="+ bDisplay);

Subscribing to Events
You can interact with the external widget to set or change subscriptions to D2 events. You can then use the
subscription to listen to messages and to extract information. Select Track selected type to track the content that is
selected by users in D2 Client, receive notifications, and view the document type
in the external widget form.
Call the subscribeToChannel() method to use this feature of Open Ajax Hub as shown in the sample code:
function subscribeEvents() {
OpenText™ Documentum® D2 Version 4.7 User 21
 Using OAH to Create and Configure a Sample External Widget

logit("subscribe to events...");
d2OpenAjaxHub.subscribeToChannel ("D2_EVENT_SELECT_OBJECT",
selectObjectCallback, true);
}

The selectObjectCallback method is an example method in the sample that dictates how the widget uses the
message received through this event.
Sending Messages
You can interact with the external widget both as a widget in a D2 Client workspace or by accessing the URL directly
through a web browser. The sample web application contains an HTML form that contains the same fields as the QF
HR a_status query form which is imported when the external widget is installed. Type a document type, select a
document status, and click the Update Doclist button. The external widget sends an Open Ajax Message to D2 to
execute the QF HR a_status query form search. The query form then functions as a Doclist widget filter because
it updates the Doclist widget with the search results.
Call the sendMessage() method to use this feature of Open Ajax Hub as shown in the sample code:
function updateDoclist() {

//Query form configuration name is defined below

var queryFormConfigName = "QF HR a_status";

//To update the doclist a new OpenAjax message will be build to be posted
//in the Hub using the D2-OAH API
var messageToSend = new OpenAjaxMessage();

// Specify a non-null ID (to pass request validation)

messageToSend.put("oam_id", "");

//In the message, we need to define what properties will be sent.

//Here a_status and r_object_type
messageToSend.put("list", "a_status¬r_object_type");

//We set the a_status value

messageToSend.put("a_status", a_status.value);
//We set the r_object_type value
messageToSend.put("r_object_type", r_object_type.value);

//set the query form config name which will be used to update the doclist
messageToSend.put("config", queryFormConfigName);

//Then we define what service and what method in the service will be called.
//We call the Search service and the runQueryFormSearch method.
//Calling this service will update the user’s last search object
messageToSend.put("eService", "Search");
messageToSend.put("eMethod", "runQueryFormSearch");
22 OpenText™ Documentum® D2 Version 4.7 User Guide
 Using OAH to Create and Configure a Sample External Widget

// When the service call completes, we can define an action to be executed.

//Here, an event will be posted.
messageToSend.put("rType", "EVENT");

// As the last search has been updated by the web service call, we will post
// the D2_ACTION_SEARCH_DOCUMENT event to display the search results
messageToSend.put("rAction","D2_ACTION_SEARCH_DOCUMENT::oam_id==node_last_sea
rch");

//The message is now ready, it can be posted in the Hub

d2OpenAjaxHub.sendMessage("D2_ACTION_EXECUTE", messageToSend);

OpenText™ Documentum® D2 Version 4.7 User 23

 Understanding Audit Events

Understanding Audit Events

This chapter contains the following topics:

• Understanding Documentum D2 Auditable Events

• Adding a New Audit Event
• Adding a Human Readable Label to the Audit Event
• Adding an Extended Label to the Audit Event
• Creating an Audit Event at Code Level

Understanding Documentum D2 Auditable

Events
Documentum D2 provides a configuration module to set up the audits that will be available to the end
user in the application.
This configuration is used by the Audit widget to present audit information to the end user, as set up by
the Administrator and in accordance with the matrix configuration.
The configuration module allows two different audit displays: normal and extended.
The configuration module might be configured to list D2 events only, or might be configured to include
out of the box Documentum DFC audit events, as per the D2 Audit module configuration.
The Documentum Audit table (refer to the Documentum Core Object Guide for full documentation on
the dm_audittrail object definition) allows five strings of data to be saved along with the event
name and user name responsible for triggering the audit event. There are also three attributes
sometimes used on the audittrail object, such as workflow_id, event_source and
version_label, which are used for D2 workflow overview and management (workflow, delegation
and task send mail features). The most important element is the Documentum Persistent Object, which
the audit event is all about.
The next section explains how to add new, correctly labelled events to D2 using the plugin system and
the D2 internal API. Currently, there is no other way to add new events. The information and
example(s) presented are in use by all D2 plugins such as C2 or O2.
You will not need the full plugin project stack to add those resources to D2. Creating a JAR with two
resources will create the event definition and make it available to the D2 product. The JAR library must
be placed in the library folder of the D2-Config web application, which should be enough to allow the
Administrator to view and set up the new events.
The last part of the documentation presents some required D2 API calls that facilitate audit creation.
Some make use of the D2 configuration engine logic, removing the decision to create the audit or not
(the decision will be based on the D2 audit configuration that applies). It is not mandatory to use the
D2 API as it might not always be available for external development; regardless, it allows for creating
a dm_audittrail object using the underlying DFC API. Please refer to the Documentum Foundation
Guide for help with this approach.

Adding a New Audit Event

1. Add a D2AuditConfig.properties file to the root of the JAR.

2. Add one entry per line to the properties file, using only alphanumeric lowercase (a-z, 0-
9) and no special characters except underscore. For example,

24 OpenText™ Documentum® D2 Version 4.7 User Guide

 Understanding Audit Events

proj_event_custom

or in this example, C2 has two entries:

c2_controled_print
c2_controlled_print_recall

3. Make the JAR available inside the D2-Config web application. Your events appear in
the D2 audit list.

Adding a Human Readable Label to the Audit

Event
1. Add a DfAuditBundle_xx.properties file to the strings/bundles path in the
JAR. Replace xx with the two-letter language code for locale (for example,
DfAuditBundle_en.properties contains labelling for English). There should be as many property
files as locales supported by your application/repository.

2. Add, at a minimum, a list of keys=values where the keys should be the event names
and the values the corresponding label. For example,

proj_event_custom = My Proj Custom event

or in this example, C2 has two event entries:

c2_controled_print = Controlled print
c2_controlled_print_recall = Controlled print recall

This is all the labelling that is required for a “normal” display. If you don’t intend to use “extended”
display, you can skip the next section.
Note: If you use the extended feature but do not define the extended label, D2 will fall back to the
normal label. You will also miss the display of the strings data holder in this mode.

Adding an Extended Label to the Audit Event

Extended display is a feature that provides more meaningful human readable information, as opposed to
simple labels. For example, you could provide the end-user with a complete phrase describing the event
logged using the additional information that may be provided with the event (there are five string data
holders where you can store information along with your audit).

1. Create additional keys in DfAuditBundle_xx.properties where the root key

will be your event name and the second node must be “extended”. Here are some
common use cases with examples:

• If you want one simple label with the only string_1 information:
proj_event_custom.extended = In Proj Custom, "$value(string_1)" was
applied
OpenText™ Documentum® D2 Version 4.7 User 25
Understanding Audit Events

string_1 to string_5 is available. Again, depending of the audit creator, some may be empty. The
bundle definition logic is tightly linked with audit usage.

• If you want to display all the string data in a raw way:

proj_event_custom.extended = My Proj Custom is using this
information: "$value(strings)"

In most audit use cases, the available string_#s (string_1 through string_5) are filled in ascending
order (1-5). You would not usually fill in information in string_5 if string_4 were vacant. As a
best practice, use string_# in order.

• If you generally use all five strings, but occasionally one of the string_#s is not
present or is empty, you can avoid an odd-looking message by using an empty
placeholder:
proj_event_custom.extended = Link to
"/$value(string_1)/$value(string_2)
/$value(string_3)/$value(string_4)/$value(string_5)"

If string_5 is not provided, you can add a third property node saying “nostring5”. When the D2 audit
bundle logic sees the audit to display and that you have provided the following bundle key, it will use
the following message instead of the generic message above:
proj_event_custom.extended.nostring5 = Link to "/$value(string_1)
/$value(string_2)/$value(string_3)/$value(string_4)"

If no string_4:
proj_event_custom.extended.nostring4 = Link to "/$value(string_1)
/$value(string_2)/$value(string_3)"

You can see that the nostring4 is not using string_5 either. That is because the normal case is that
you do not fill string_5 if string_4 is missing. There is no conditioning logic that detects
string_5 but no string_4. We detect the key definition that looks the best suitable to the audit case
we have; it may not match all your different use cases.
• If you want to make the message more reusable for other labels, you can use five
different combinations of bundle keys.; In each of them, define what represents the
“string_#” data as it will provide more meaning to the end-user and represents only
one bundle key to change:
proj_event_custom.extended.string_3Label = reason

The key can then be used inside other label:

proj_event_custom.extended.nostring4 = Link to "/$value(string_1)
/$value(string_2)" where $value(string_3Label) is "$value(string_3)"

The bundle definition will look like this (avoid making any cyclic use of key):
proj_event_custom.extended.nostring4 = Link to "/$value(string_1)
/$value(string_2)" where $value(string_3Label) is "$value(string_3)"
proj_event_custom.extended.string_3Label = reason

• If only one string is present among the others:

proj_event_custom.extended.onlystring4 = My event is using
"$value(string_4)"
26 OpenText™ Documentum® D2 Version 4.7 User Guide
 Understanding Audit Events
For example, in the C2 plugin, we have the following partial event bundle definition, where the goal
was to define the controlled printing feature.:
c2_controled_print=Controlled print
c2_controled_print.extended.juststring4=Controlled print with :
$value(string_4Label)
equals "$value(string_4)"
c2_controled_print.extended.nostring5=Controlled print with :
$value(string_3Label) equals "$value(string_3)" and
$value(string_4Label) equals "$value(string_4)"
c2_controled_print.extended.nostring4=Controlled print with :
$value(string_3Label) equals "$value(string_3)"
c2_controled_print.extended=Controlled print with :
$value(string_3Label) equals "$value(string_3)",
$value(string_4Label) equals "$value(string_4)
" and $value(string_5Label) equals "$value(string_5)"
c2_controled_print.extended.string_3Label=recipient
c2_controled_print.extended.string_4Label=reason
c2_controled_print.extended.string_5Label=field n°3

For example in D2, we have this simple declaration where all strings are being used. The unlink event
has its strings filled with each folder level; sometimes five levels deep, sometimes two levels deep:
dm_unlink.extended=Unlink from
"/$value(string_1)/$value(string_2)/$value(string_3)
/$value(string_4)/$value(string_5)"
dm_unlink.extended.nostring5=Unlink from
"/$value(string_1)/$value(string_2)
/$value(string_3)/$value(string_4)"
dm_unlink.extended.nostring4=Unlink from
"/$value(string_1)/$value(string_2)
/$value(string_3)"
dm_unlink.extended.nostring3=Unlink from
"/$value(string_1)/$value(string_2)"
dm_unlink.extended.nostring2=Unlink from "/$value(string_1)"

Another example in D2 where signoff is not always configured with user intention. When intention is
available, we display it, when not, we do not:
d2_import_signoff=Signoff for import
d2_import_signoff.extended.nostring1=Signoff for import
d2_import_signoff.extended=Signoff for import with this intention :
$value(string_1)

Creating an Audit Event at Code Level

The pre-requisite for code level event creation is to have C6-Common and D2-API libraries in your
project classpath.
An audit event is linked to an existing DFC object, and requires an event name and a username (user
responsible for triggering the audit). You can also store five additional strings (placeholders), which
correspond to the five table cells in the Audit Widget display.

1. Create your code level event according to the use cases described here, which employ
two different APIs (the first one conditioning the use of the second one):

• If you want to create an audit only if the configuration engine has the event name
set up to be displayed:
com.emc.d2.api.config.modules.audit.D2AuditConfig
OpenText™ Documentum® D2 Version 4.7 User 27
Understanding Audit Events
Two static methods are provided:
IDfPersistentObject apply(IDfPersistentObject persistentObject,
String eventName, String string1,
String string2, String string3, String string4, String string5)
throws DfException;

IDfPersistentObject apply(IDfPersistentObject persistentObject,

String eventName, String userName,
String string1, String string2, String string3, String string4,
String string5) throws DfException;

The only difference between the two declarations is the passing of the user name. In the first API call,
the username (event creator) is not passed (it is null). This will cause the “loginUserName” to be
retrieved from the current DFC Session object currently being used by the persistentObject.
In the second API call, the username (event creator) is passed. Your event will not be created if the D2-
Config context engine and audit configuration module indicates it is not audited (checking D2-Config
context engine either based on type and/or group).

• If you want to create an audit and have it display only if the configuration engine
has the event name set up.
com.emc.common.dctm.objects.DfAuditTrailEx

There are multiple method signatures available, mainly relying on this first one, simplifying the
different parts that are not meant to be used.
IDfPersistentObject create(IDfPersistentObject persistentObject,
IDfSession privateSession, String eventName,
String userName, String string1, String string2, String string3,
String string4, String string5, List<String>
attributes, String eventSource, IDfId workflowId, String version)
throws DfException;

The other commonly used methods are:

IDfPersistentObject create(IDfPersistentObject
persistentObject,
String eventName, String userName, String
string1, String string2, String string3, String string4,
String string5, List<String> attributes) throws DfException;

In the method shown above, the session is retrieved from the persistent object directly.
IDfPersistentObject create(IDfPersistentObject
persistentObject, IDfSession privateSession,
String eventName, String userName, String string1, String
string2,
String string3, String
string4, String string5, List[String] attributes) throws
DfException;

In the method shown above, the session object can be defined, and will be used to extract the username
and create the audit object.
Note: You can see a list of string attributes. These are used, for example, to audit properties. Each of
the strings are the attribute/property name of the “persistentObject”. The previous values from the
persistent object are extracted and both the old and new list are part of the audit trail. They will be used
by our audit engine to present them as old value and new value or added/removed value.
28 OpenText™ Documentum® D2 Version 4.7 User Guide
 Understanding Audit Events
Here is a longer example, with the context of use:
D2 create user is auditing using D2AuditConfig statics since audit is needed only if configured.
C2 recall printing system will use “DfAuditTrailEx” statics, since the plugin is basing its control logic
for printing on audit trail existence.
The decision point between those two APIs, is dependent on whether or not you have a plugin logic
base on audit event existence.
You have to take into consideration the cost of creating an in terms of resources (DB, JVM) but also in
terms of space (DB). For example, it is preferable to create an audit for a batch of work, rather than an
audit per task in a batch.
When possible, it is recommended to use the D2 API, as it has been optimized for session management
when a lot of events are to be created. Although it is not always possible to use the API for external
development, you can still rely upon the DFC API for the same functionality (please refer to the
corresponding DFC documentation).

OpenText™ Documentum® D2 Version 4.7 User 29

 Chapter 7
Creating and Configuring a Custom
Plug-in
This chapter contains the following topics:

• Understanding Custom Plug-ins

• Overview of the Template Plug-in Examples
• Downloading and Setting Up the Template Plug-in
• Building, Installing, and Verifying the Template Plug-in
• Configuring a Menu Item for the Template Plug-in
• Creating a New Plug-in Using the Template
• Configuring a Custom Action
• Understanding Service Interface Overrides
• Setting Up D2 Service Overrides
• Deploying D2 Plug-ins
• Extending C2 PDF functionality
Understanding Custom Plug-ins
You can create and configure custom plug-ins using the Java classes and the resources that are
packaged with the D2 API framework to:
• Add features as custom actions.
Configuring a Custom Action contains instructions for creating and configuring a custom action.
• Modify existing features by changing the pre-processing, post-processing, and the
overriding D2 services.
Setting Up D2 Service Overrides contains instructions for modifying the D2 services and
Understanding Service Overrides contains information about the various overrides you can use.
OpenText Documentum D2 D2FS API JavaDoc contains more information on the available
services and actions.
The Read Me — Getting Started with D2 Plugin.txt file contains more information on creating and
configuring a custom plug-in. This file is available in the SDK package.

OpenText™ Documentum® D2 Version 4.7 User 31

Creating and Configuring a Custom Plug-in

Overview of the Template Plug-in Examples

The template plug-in located in the Plugins folder of the D2 4.5 SDK.zip archive contains the following
three examples:
Customizing Content Export
This example for customizing content export explains the procedure to use the condition service override, add a
custom service (IPluginAction), and configure error reporting. The resulting plug-in allows end users to use
a menu item in D2 Client to download dynamically-generated custom content using the D2 web service. To do
this, the plug-in uses D2 OpenAjaxHub to post an event named D2_ACTION_EXPORT_FROM_URL to trigger
content download from the URL contained in a parameter.
The plug-in consists of the following classes:

• D2CustomService implements the IPluginAction interface to allow being called as a

standard D2 web service. The class contains the getCustomDownloadURL method that returns a
URL with dynamic IDs to the ExportContent servlet.

• D2ExportServicePlugin intercepts the standard D2ExportService web service that is

called by the ExportContent servlet. The class overrides the exportTo method to send
custom content to D2.

• D2 uses D2PluginTemplateVersionand D2PluginVersionfor plug-in detection.

After configuring a menu item using D2 Config, an end user can click the menu item in D2 Client to trigger the
following chain of events:

1. The plug-in calls the getCustomDownloadURL method in the D2CustomService service.

2. The method returns a URL to the ExportContent servlet in an oam_value attribute.

3. The servlet posts the URL as a parameter of the D2_ACTION_EXPORT_FROM_URL event.

4. The D2 applet detects the event and triggers a download using the ExportContent servlet.

5. The ExportContent servlet retrieves content from the D2ExportService service.

6. The D2ExportServicePlugin intercepts the call and sends the custom content.

Overriding a Service with Post-Processing

This example performs a D2 Service but adds post-processing to make object_name values appear in upper
case.
The plug-in consists of the D2ContenServicePlugin class.

Overriding a Service with Pre-Processing

This example performs a D2 Service but adds pre-processing to add a timestamp suffix to the title attribute.
The plug-in consists of the D2CreationServicePlugin class.

Downloading and Setting Up the Template

Plug-in
1. Download D2 4.5 SDK.zip to a temporary location.

2. Extract the Plugins folder from D2 4.5 SDK.zip

32 OpenText™ Documentum® D2 Version 4.7 User Guide

 Creating and Configuring a Custom Plug-in
3. Open your IDE and select the extracted Plugins folder as a workspace.
If you select the YourCo-PluginName folder, the IDE might not recognize the project.

4. Import the project to the workspace. In Eclipse:

a. Navigate to File > Import.
b. Select General > Existing Projects into Workspace and click Next.
c. In Select root directory, click Browse and select the YourCo-PluginName folder.
d. Click Finish.

5. Configure the Java Build Paths for D2. In Eclipse:

a. Right-click YourCo-PluginName in the Package Explorer and click Properties.

b. Click Java Build Path in the Properties for YourCo-PluginName dialog box.
c. Click the Libraries tab.
d. Click Add Variable, then click Configure Variables.

e. Click New and fill out the form as described in the following table:

Field Description
Name Type D2_4x_LIB
Path Type the path to the WEB-INF/lib folder in the D2 web application. For example:

C:/Program Files/Apache Software Foundation/Tomcat

6.0/webapps/D2/WEB-INF/lib

f. Click New and fill out the form as described in the following table:

Field Description
Name Type D2_4x_CLASSES
Path Type the path to the WEB-INF/classes folder in the D2 web application. For example:

C:/Program Files/Apache Software Foundation/Tomcat

6.0/webapps/D2/WEB-INF/classes

g. Click New and fill out the form as described in the following table:

Field Description
Name Type D2_DFC_JAR
Path Type the path to the folder containing DFC.jar file. For example:

C:/OpenText-dfs-sdk-6.7.2/lib/java/dfc/dfc.jar
Eclipse will not show any errors now.

h. Click OK until you are back at the Package Explorer window.

6. Edit build\build.propertiesto set D2_4x_LIB, D2_4x_CLASSES, and D2_DFC_JAR
variables for use by Ant build (using the same paths from the above step). For example:
D2_4x_LIB = C:/Program Files/Apache Software Foundation/Tomcat
6.0/webapps/D2/WEB-INF/lib

D2_4x_CLASSES = C:/Program Files/Apache Software Foundation/Tomcat

6.0/webapps/D2/WEB-INF/classes
OpenText™ Documentum® D2 Version 4.7 User 33
 Creating and Configuring a Custom Plug-in

D2_DFC_JAR = C:/OpenText-dfs-sdk-6.7.2/lib/java/dfc/dfc.jar

Building, Installing, and Verifying the Template

Plug-in
1. Build the plug-in:

a. In Eclipse, expand the build folder in Package Explorer.

b. Right-click build.xml and navigate to Run As > Ant build
When your IDE finishes building the .jar file, the dist folder contains
YourCo-PluginName.jar.

2. Stop the web application server.

3. Copy YourCo-PluginName.jar to the WEB-INF/lib folder of the D2 web application. For

example,
C:/Program Files/Apache Software Foundation/Tomcat
6.0/webapps/D2/WEB-INF/lib

4. Start the web application server.

5. Verify the plug-in installation:

a. Log in to D2 Client.
b. Navigate to Help > About D2 from the menu bar.

c. Look for YourCo-PluginName v1.0.0 (0001) in the list of Plugins.

Configuring a Menu Item for the Template

Plug-in
Configure a menu item using D2 Config to allow end users to call the custom download action.

1. Log in to D2 Config and navigate to Go to > Menu D2 to open the D2 Client menu
configuration page.
2. Add a new menu item to the menu in which you want the button to appear. OpenText Documentum D2
Administration Guide contains further instructions for configuring a D2 Client menu.

3. Fill out the form for the new menu item as described in the following table.

Field Description
Label en Export Custom Content
Shortcut Ctrl+D
Action Calling service’s method
Service D2CustomService
Method getCustomDownloadURL
Selection Select MULTI to allow end users to select multiple
content for the download action.
Type Select EVENT to post an event if the web service
call is successful.
Action D2_ACTION_EXPORT_FROM_URL
34 OpenText™ Documentum® D2 Version 4.7 User Guide
 Creating and Configuring a Custom Plug-in

4. Click Save.

Creating a New Plug-in Using the Template

You must declare and insert the necessary resources using the following folder tree for D2 to recognize the
custom plug-in:
<company name>-<plug-in name>
|--src
|--com
|--<your namespace>
|--<plug-in name>
|--> D2PluginVersion.java
|--> <plug-in name>Version.java
|--> <plug-in name>Version.properties

1. Rename the YourCo-PluginNameproject. For example: DaveCo-CoolPlugin

2. Rename com.yourdomainhere.yourplugin in Eclipse to your domain namespace and

package name for each package in the plug-in template.
For example: com.daveco.coolplugin

3. Optionally, rename PluginNameVersion.javaand PluginNameVersion.properties

For example: CoolPluginVersion.javaand CoolPluginVersion.properties
If you rename the files, you must edit build.properties to reflect the name change.

4. Edit build.properties and change project.version.file to reflect your package

structure and the plug-in properties file name.
For example: /src/com/daveco/coolplugin/CoolPluginVersion.properties

5. Edit PluginNameVersion.properties or CoolPluginVersion.properties (if you have

renamed it) to set the company, project, and so on.

6. Remove the example plug-in classes and replace them with your plug-in implementation. For
example: *.webfs.services.content and *.webfs.services.create

7. Re-run .\build\build.xml to rebuild your plug-in.

Configuring a Custom Action

1. Create a Java class in the <project folder>/src/com/<your
namespace>/<plug-in name>/webfs/services/custom/ folder.

2. Import the following resources:

import java.util.List;
import com.emc.d2fs.dctm.plugin.IPluginAction; import
com.emc.d2fs.dctm.web.services.D2fsContext; import
com.emc.d2fs.models.attribute.Attribute;

The OpenText Documentum D2 D2FS API JavaDoc contains more information about the packages that
you can use to configure a custom action.

3. Implement IPluginAction:

OpenText™ Documentum® D2 Version 4.7 User 35

 Creating and Configuring a Custom Plug-in
public class <name of the class> implements IPluginAction

4. The class must contain a method that has at minimum the following format:
public List<attribute> <methodName>(D2fsContext context);
For example, the YourCo-PluginName plug-in sample contains the following method declaration for
D2CustomService.java:

public List<Attribute> getCustomDownloadURL(D2fsContext context)

throws UnsupportedEncodingException, DfException, D2fsException

5. After building and installing the plug-in, create a menu button in D2 Config to allow end users
to perform the custom action. The OpenText Documentum D2 Administration Guide contains
further instructions for configuring a D2 Client menu.
For example, Configuring a Menu Item for the Sample Plug-in, page 34 contains the instructions for creating a
menu button for the YourCo-PluginName plug-in sample.
Understanding Service Interface Overrides
You can override all D2 services interfaces using the @override annotation.
Pre-Processing
You can add data processing before a service by adding code before the super call. The following example code
adds a custom timestamp to the end of a content title before the service creates content properties. The pre-
processing ensures that content created using the plug-in have a timestamp at the end of the title:
/** Override createProperties to add custom pre-processing.
*
*/
@Override
public String createProperties(Context context, java.util.List<Attribute>
parameters) throws Exception {
// pre-processing -- look for ’title’ attribute and add a custom
//timestamp at the end.

for(Attribute attr : parameters){

if (attr.getName().equals("title")){
String timeStamp = new SimpleDateFormat("yyyyMMdd_HHmmss").
format(Calendar.getInstance().getTime());
attr.setValue(attr.getValue() + " : " + timeStamp); break;
}
}
return super.createProperties(context, parameters);
};

Post-Processing
You can add data processing after a service by adding code after the super call. The following example code runs
the result of the service through a capitalization process. The post-processing ensures that the plug-in returns the
name of the object_name attribute in upper-case letters.
/** Override getContent() to demonstrate post processing
(make object_name attributes upper case).
*
NOTE: If overriding getContent() you may want to similarly override
getFilteredContent().
*

36 OpenText™ Documentum® D2 Version 4.7 User Guide

 Creating and Configuring a Custom Plug-in
*/
@Override
public DocItems getContent(Context context, String contentId, String
contentTypeName, String viewMode, String checkChildren)
throws Exception {

LOGGER.debug("D2ContentServicePlugin calling super.getContent()...");

// Call base class implementation to get the default results.

DocItems result = super.getContent(context, contentId, contentTypeName,
viewMode, checkChildren);

LOGGER.debug("D2ContentServicePlugin post processing items...");

// Return post processed results return postProcessItems(result);

}

Overriding the Process

You can perform a replacement override by forcing the service to return a different value than the original super
method. The following example overrides the original exportTo class and returns dh
= new DataHandler(new FileDataSource(new File(myFile))).
@InjectSession
public FileContent exportTo(Context context, String parentId, String
typeName, String colType, String exportType, String fileName) throws
Exception
{
FileContent result = null;

OpenText™ Documentum® D2 Version 4.7 User 37

Creating and Configuring a Custom Plug-in

D2fsContext d2fsContext = (D2fsContext) context;

ParameterParser parameterParser = d2fsContext.getParameterParser();
LOGGER.info ("D2ExportServicePlugin Before exportTo");
// If the parameter custom_call is sent and is true,
// the customization will be used.
if (parameterParser.getBooleanParameter("custom_call"))
{
// overridden
LOGGER.info ("custom_call, overridden...");

List<String> ids = StringUtil.split(parameterParser.

getStringParameter("id"), "-");
LOGGER.info ("SELECTED IDs = " + ids);

//Retrieve user session

IDfSession session = d2fsContext.getSession();

//Prepare file content for result result = new FileContent();

result.setName("MyFile.pdf"); result.setMime(IDfFormatEx.PDF);
result.setFormat(IDfFormatEx.PDF);

//SETUP Here!!!: This file must exist on your server

//(with sufficient permissions).
String myFile = "c:\\temp\\MyFile.pdf";
DataHandler dh = new DataHandler(new FileDataSource(new File(myFile)));
result.setFileContent(dh);
}
else {
//not overridden; proceed with default behavior.

LOGGER.info ("(not overridden) calling super.exportTo()...");

result = super.exportTo (context, parentId, typeName, colType, exportType,

fileName);
}

return result;
}

Throwing Exceptions
You can use Exception() and D2fsException() to report exceptions or errors encountered in your Service
extension or Custom Action code back to D2 and the end user. The following example shows how to use
D2fsException():

public List<Attribute> getCustomDownloadURL(D2fsContext context) throws

UnsupportedEncodingException, DfException, D2fsException
{
LOGGER.debug("getCustomDownloadUrl()...");

38 OpenText™ Documentum® D2 Version 4.7 User Guide

 Creating and Configuring a Custom Plug-in

/**
Error reporting -- Note that when you need to report an error to D2
and the user, you can simply throw an Exception() or D2fsException(),
whichever is compatible with the api your are overriding
For example, this custom action throws D2fsException()
*
*/
Boolean bNeedToReportAnError = false;
//
if (bNeedToReportAnError) {
// Error detected; Build your localized message and throw the
//Exception() to notify user.
throw new D2fsException("A problem was encountered with your custom
export...");
}

// Code omitted for example clarity

return result;
}

Setting Up D2 Service Overrides

Use the following folder structure when you want to create a class to override D2 services:
<company name>-<plug-in name>
|--src
|--com
|--<your namespace>
|--<plug-in name>
|--webfs
|--services
|--<name of the service package>
|--> <name of the service>Plugin.java

1. Determine the <name of the service>.

The com.emc.d2fs.interfaces section of OpenText Documentum D2 D2FS API JavaDoc contains a list
of D2FS interfaces prefixed by the letter I. For example, the sample D2ExportServicePlugin
class is based on the IExportService interface.
To determine the <name of the service>, replace the prefix I with D2. For example, in the sample the
interface IExportService uses the D2 service D2ExportService.
2. Create a .java file named <name of the service>Plugin.java for the services class to
configure the process in the <company name>-<plug-in name>/src/com/<your
namespace>/<plug-in name>/webfs/services/<name of the service
package>/ folder.
3. Create and name the class <name of the service>Plugin.
For example, the sample uses the service D2ExportService to name its class
D2ExportServicePlugin.

4. Extend the service class with the <name of the service> and implement the
OpenText™ Documentum® D2 Version 4.7 User 39
Creating and Configuring a Custom Plug-in
ID2fsPlugininterface.
For example, the sample declares the class:
public class D2ExportServicePlugin extends D2ExportService
implements ID2fsPlugin

The ID2fsPlugin interface forces the implementation of two methods:

• getFullName: Returns the full plug-in name with its version number. The
method is called by the About dialog box in D2.

• getProductName: Returns the plug-in name to determine whether the plug-in

should be executed based on the D2 configuration matrix.

Deploying D2 Plug-ins
1. Create the plug-in .jar file.
2. Copy the plug-in .jar file to the <install path of D2>/WEB-INF/lib/ folder. For
example:
C:\apache-tomcat-<version>\webapps\D2\WEB-INF\lib

3. Restart the web application server.

4. Verify the plug-in installation by logging in to D2 Client and navigating to Help >
About.

Create a Custom Dialog

Custom D2 dialogs can be used to build a custom UI to implement application specific behavior.
Creating a dialog requires 3 artifacts:

1. Java Class - Controlling the behavior of XML

2. Dialog XML – UI Representation
3. Properties File – Mange UI labels defined on XML

The artifacts need to follow the following folder structure:

|--src (Java Source Folder)
|--com
|--<your namespace> (ex: <company Name>.<App Name>)
|--webfs
|--dialogs
|--> <name of the Dialog>.java

|--<D2 App>/WEB-INF/classes
|--xml
|--dialogs
|--> <name of the Dialog>.xml

|--<D2 App>/WEB-INF/classes
|--strings
|--dialogs

40 OpenText™ Documentum® D2 Version 4.7 User Guide

 |--> <name of the Dialog>.properties

Here is a sample snippet to build a custom Dialog.

CustomDialog.java:

This java class must be wrapped in a jar and copied to /D2/WEB-

INF/lib folder on application server.

package com.ot.myapp.webfs.dialogs

public class CustomDialog extends AbstractDialog Implements ID2Dialog

{

public XmlNode buildDialog(D2fsContext context, List<Attribute>

attribute) throws Exception
{
// Implement dialog processing code here

public XmlNode validDialog(D2fsContext context) throws Exception

{
// Implement dialog processing code here

public XmlNode cancelDialog(D2fsContext context, List<Attribute>

attribute) throws Exception
{
// Implement dialog processing code here

CustomDialog.xml

<?xml version="1.0" encoding="utf-8"?>

<dialog id="CustomDialog" buttons_right="false" focus="" height="250"

width="600" resizable="true" signoff_creation="false" signoff_edit="false"
signoff_import="false" signoff_intention_dictionary=""
signoff_intention_required="false">
<content>

<fieldset label_en="Please select Executed Legal Document

Folder to Delete">
<combo id="exfolder" assistance_type="dql"
assistance_dql="select object_name from dm_folder" sorted="true"
required="true" label_en="Folder Name"/>

</fieldset>
</content>
<buttons>
<button id="buttonOk" action="validDialog()"></button>
<button id="buttonCancel" action="cancelDialog()"/>
</buttons>
</dialog>

OpenText™ Documentum® D2 Version 4.7 User 41

Creating and Configuring a Custom Plug-in
CustomDialog_en.properties

buttonCancel=Cancel
buttonOk=OK

Deploying Custom Dialog

1. Create the .jar file.

2. Copy the .jar file to the <install path of D2>\WEB-INF\lib\folder. For example:
C:\apache-tomcat-<version>\webapps\D2\WEB-INF\lib

3. Copy XML file to the <install path of D2>\WEB-INF\classes folder. For example:
C:\apache-tomcat-<version>\webapps\D2\WEB-INF\classes\xml\dialog

4. Copy properties file to the <install path of D2>\WEB-NF\classes\strings\dialog

folder. For example:
C:\apache-tomcat-<version>\webapps\D2\WEB-
NF\classes\strings\dialog

5. Restart the web application server.

Open Custom Dialog from a Menu

Create a custom menu item as mentioned in the screenshot below to launch this
custom dialog.

Extending C2 PDF functionality

The PdfConverterListener.java sample code shows how to convert or process any PDF
output generated by C2 into a linearized PDF. The PdfConverterListener.java sample is based
on the Big Faceless (BFO) Java PDF library that supports post processing capabilities such as
linearization for faster display of PDF documents downloaded from the web. The
PdfConverterListener.java sample implements the IPdfProcessorListener API and can be
packaged as a JAR and installed where the PDF-API.jar files are located along with third party library
dependencies. The PDF-API.jar is located under /WEB-INF/lib in D2-Config and D2-BOCS. It can

42 OpenText™ Documentum® D2 Version 4.7 User Guide

 also be found on JMS, BOCS, and Content server installations
Out-of-the box, the sample code can be run by providing the input path of a valid PDF file and an
output path for the linearized PDF file.

1. Import the following resources

import java.io.File;
import java.io.OutputStream;
import com.emc.pdf.api.IPdfProcessorListener

2. Implement IPdfProcessorListener
public class implements IPdfProcessorListener
3. Provide the name of the class. The sample uses public class PdfConverterListener
An example of the sample code is as follows:

package your.package.name;
import java.io.File;
import java.io.OutputStream;
import com.emc.pdf.api.IPdfProcessorListener;

public class PdfConverterListener implements IPdfProcessorListener

{
@Override
public void onAfter(Object abstractData, File file,
OutputStream outputData, String userPassword, String
ownerPassword)

In this sample:

• <file> is the input source

• <OutputStream> generates the output after the change is made by the library, code, or
logic.

• <File> is the resulting PDF encrypted using userPassword or ownerPassword.

• <abstractData> is converted to a java.util.Map and contains all available data used

during processing.

OpenText™ Documentum® D2 Version 4.7 User 43