EMC White Paper

BPS http Listener

Installing and Configuring

March 2006
Copyright © 2005 EMC Corporation. All rights reserved.
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.
EMC2, EMC, and EMC Documentum product names are trademarks of EMC Corporation. All other trademarks used herein are the
property of their respective owners. All other brand names are trademarks or registered trademarks of their respective owners.

Installing and Configuring BPS http Listener 2

WHAT IS BPS.............................................................................................................................................. 4

HOW HTTP LISTENER WORKS.............................................................................................................. 4

HOW HTTP LISTENER WORKS.............................................................................................................. 4

INSTALLATION OF BPS HTTP LISTENER........................................................................................... 4

CONFIGURING THE BPS HANDLERS .................................................................................................. 5

CREATING A TEST HTML PAGE ........................................................................................................... 7

TESTING THE APPLICATION.................................................................................................................. 7

LOCATING THE SAVED MESSAGE IN THE DOCBASE ................................................................... 8

SUMMARY- BPS HTTP INSTALLATION AND CONFIGURATION................................................... 9

Installing and Configuring BPS http Listener 3

What is BPS
Business Process Services (BPS) provides the gateway to access Docbase for a non
Documentum user. It allows HTTP, SMTP of JMS message to be stored directly in the
Docbase. When an http, SMTP or JMS message is sent to BPS http listener Servlet URL,
email address or JMS queue; the listener intercepts the message and processes it to a
protocol neutral format. The message is then passed to the BPS message handler. The
message handler opens a connection to the Docbase and stores the message as virtual
document. The attachment gets stored as child nodes of the virtual document.

How http Listener Works

The http message listener is implemented as a Servlet. It gets installed as a part of BPS
web application. The URL to access the http listener Servlet is

http://<servername>:<portnumber>/bps/http/http
or
https://<servername>:<portnumber>/bps/http/http

As you can see from the URL, the http listener can use both http and https protocol.
However it should be kept in mind that application server uses two separate ports to
communicate with http and https protocol. If we provide http protocol port number (say
8080) to construct the https URL, it will not work. This is a common error one can make
while configuring BPS http listener. In the following pages we will step through the
installation, configuration and testing of BPS http listener.

Installation of BPS http Listener

1. Run the installer
2. Click “I accept the terms of the license agreement” and click “Next”.
3. Select http listener to install and click “Next”.
4. To install the Documentum Foundation Classes (DFC) developer documentation,
click the Developer Documentation check box.
5. To request installation of a Microsoft installer package (.msi file) for the DFC
primary Interop assembly, click the Primary Interop Assembly Installer check
box. (If you select this option, the Business Process Services installation program
places the installation package for the DFC primary Interop assembly into the
setup directory of the DFC program root directory). Click Next.
6. If the machine has no other Documentum software installed on it, enter basic
configuration information for DFC.
7. Accept the default DFC program root directory (C:\Program Files\Documentum)
or enter a different directory and click “Next”.

Installing and Configuring BPS http Listener 4

 8. Accept the default user directory (C:\Documentum) or enter a different directory
and click Next.
9. Enter a DocBroker host name and port number. If the computer has DFC pre-
installed, then BPS will use the existing dmcl.ini.
10. Click Next on the summary screen showing the software to be installed.
11. The selected BPS components will get installed on the host.

Configuring the BPS Handlers

BPS configuration for handlers are kept in default.xml file. It is be located at
drive:\Documentum\config\bps

1) Navigate to The default.xml file and open it for edit using a ASCII editor like
Notepad.
2) Configuring <connections> element of this file. In the <connections> element we
have to provide the connection details to Docbase, such as Docbasename, username,
password etc. A sample <connections> element entry should look like this:-

<connections>
<docbase-connection name=”connection”>
<docbase-name>zebra</docbasename>
<user-name>dmadmin</user-name>
<password>mypassword</password>
</docbase-connection>
</connections>

3) Configuring <handlers> element.

This element specifies the message handlers available to BPS message listeners.
Many out of the box handlers are provided with BPS but all of them are disabled by
surrounding them within XML comment tag <!-- -->
Either enable some of them or point towards your own custom handler class like this
<handlers>
….
….
<handler name=”LinkToFolderExample”>
<service-name>
com.documentum.bps.handlers.LinkToFolderService
</service-name>
<params>
<param name=”folderName” value=”/bpsinbound/”/>
</params>
</handler>
</handlers>

4) Configuring <listeners> element

Listeners element turns on the SSL capabilities of Local and remote listeners. Set the
<allow-non-ssl> flag true or false as per your requirements. For our http listener test,
we would use non-ssl connection, so make sure the value for the element is “true”.

Installing and Configuring BPS http Listener 5

5) Save the default.xml.

A complete default.xml file for our test setup will look something like this. Replace the
bold letters with your own Docbase, user, password and connection names. You can have
multiple connections defined for multiple docbases.

?xml version="1.0" encoding="UTF-8"?>

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<processors>
<local name="default"/>
</processors>
<connections>
<docbase-connection name="myconnection1">
<docbase-name>mydocbase1</docbase-name>
<user-name>myname1</user-name>
<password>mypassword1</password>
</docbase-connection>
<docbase-connection name="myconnection2">
<docbase-name>mydocbase2</docbase-name>
<user-name>myname2</user-name>
<password>mypassword2</password>
</docbase-connection>
</connections>

<handlers>
<handler name="ErrorHandlerService">
<service-name>com.documentum.bps.handlers.ErrorHandlerService</service-name>
</handler>
<handler name="Redirector">
<service-name>com.documentum.bps.handlers.SubjectMessageFilter</service-name>
</handler>
<handler name="LinkToFolderExample">
<service-name>com.documentum.bps.handlers.LinkToFolderService</service-name>
<params>
<param name="folderName" value="/bpsinbound"/>
</params>
</handler>
</handlers>

Installing and Configuring BPS http Listener 6

 <listeners>
<http-listener>
<local-listener>
<allow-non-ssl>true</allow-non-ssl>
</local-listener>
<remote-listener>
<allow-non-ssl>true</allow-non-ssl>
</remote-listener>
</http-listener>
</listeners>
</config>

Creating a Test html Page

We would need a test html page to test the http listener. Create html page out of the code
provided below. This simple page submits a form to http listener after populating BPS
http listener parameters in the form parameters.
<HTML>
<h1>BPS http listener and LinkToFolder handler test</h1>
<form method="post" enctype="multipart/form-data"
ACTION="http://localhost:8080/bps/http/http">
<input type="hidden" name="DctmBpsHandler" value="LinkToFolderExample">
<input type="hidden" name="DctmBpsId" value="4b08ac1980001d29">
Connection name: <input type="text" name="DctmBpsConnection" size="20" ><br/>
File1 to upload: <input type="file" name="file to upload1" id="file1" size="20">
<br/>
File2 to upload: <input type="file" name="file to upload2" id="file2" size="20">
<br/>
<br/>
<input type="submit" value="Submit">
</form>
</HTML>

Create a file called test.html out of this code and save it in the bps root folder.

Testing the Application

Start the application server where BPS is deployed and then invoke the html page by
typing the following URL in your browser

http://<servername>:<portnumber>/bps/test.html

Installing and Configuring BPS http Listener 7

A page like Fig 1 below should appear in your browser. If not then please check if your
application server is running or if it has been installed properly

Fig 1

Fill up the connection name such as myconnection1 and then select a file to upload and
then hit submit. This will cause the html form to be submitted to the BPS http listener,
which will pass the message to LinkToFolder message handler and the file will be stored
in bpsinbound folder. Once message handler succeeded, it will present a success page as
shown in Fig 2.

Fig 2

Locating the Saved Message in the Docbase

We have configured the LinkToFolder handler to save the message to bpsinbound folder.
If you browse to the bpsinbound folder, you will found a new virtual document has been
created by the LinkToFolder handler as shown in Fig 3.

Installing and Configuring BPS http Listener 8

Fig 3

Expanding the root virtual document will show the attached file.

Fig 4

Summary- BPS http Installation and Configuration

BPS http listener can be installed by selecting proper option in the BPS installer. To run
the http listener, you will require an application server like Tomcat. The handler is
implemented as Servlet. Before using the listener and the message handlers, BPS
default.xml file needs to be configured. Please follow the instruction provided in this
Whitepaper.to configure the default.xml file. Once it is configured; the http listener is
ready for test. Use the test.html file provided in this White Paper to test the http listener.

Installing and Configuring BPS http Listener 9

About EMC
EMC Corporation (NYSE: EMC) is the world leader in information storage systems, software, networks,
and services, providing automated networked storage solutions to help organizations get the maximum
value from their information, at the lowest total cost, across every point in the information lifecycle.
Information about EMC’s products and services can be found at www.EMC.com

About Documentum Software from EMC

Documentum software from EMC Corporation includes enterprise content management solutions that
enable organizations to unite teams, content and associated business processes. With a single platform,
EMC Documentum software enables people to collaboratively create, manage, deliver, and archive the
content that drives business operations, from documents and discussions to e-mail, Web pages, records, and
rich media. The Documentum enterprise content management platform makes it possible for companies to
distribute all of this content in multiple languages, across internal and external systems, applications, and
user communities. As a result of deploying Documentum, thousands of the world’s most successful
organizations are harnessing corporate knowledge, accelerating time to market, increasing customer
satisfaction, enhancing supply chain efficiencies, reducing operating costs, and improving their overall
competitive advantage.

For more information about Documentum enterprise content management, visit

www.emc.com/documentum or call 800.607.9546 (outside the U.S.: +1.925.600.5802).

Installing and Configuring BPS http Listener 10