EMC White Paper. BPS http Listener. Installing and Configuring

Transcription

1 EMC White Paper BPS http Listener Installing and Configuring March 2006

2 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. EMC 2, 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

3 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

4 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, 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 or 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

5 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 preinstalled, 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

6 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=" <processors> </processors> <connections> </connections> <local name="default"/> <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> <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

7 <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=" <input type="hidden" name="dctmbpshandler" value="linktofolderexample"> <input type="hidden" name="dctmbpsid" value="4b08ac d29"> 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 Installing and Configuring BPS http Listener 7

8 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

9 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

10 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 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 , 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 or call (outside the U.S.: ). Installing and Configuring BPS http Listener 10