Sie sind auf Seite 1von 121

EMC Documentum

Business Activity Monitor

Version 6.7

Installation Guide

EMC Corporation
Corporate Headquarters:
Hopkinton, MA 017489103
15084351000
www.EMC.com

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.
For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com. All other trademarks used
herein are the property of their respective owners.
Copyright 2011 EMC Corporation. All rights reserved.

Table of Contents

Chapter 1

Overview of Business Activity Monitor .......................................................... 11


Prerequisites for installing the BAM server ......................................................... 11
Overview of the BAM installation procedure .......................................................12
Downloading the BAM product installation files...................................................12
Unpacking BAM product installation files............................................................13
Installing BAM without a connection to the Internet .............................................14
Installing the BAM server ..................................................................................14
Installing the Process Reporting Services Client and Crystal Reports...................15
Installing the preconfigured dashboard ..............................................................15

Chapter 2

Preparing the Database ..................................................................................17


Overview of preparing the BAM database ..........................................................17
Preparing the Microsoft SQL Server database....................................................18
Preparing the Oracle database..........................................................................19
Preparing the DB2 database .............................................................................20
Sizing the BAM database..................................................................................23

Chapter 3

Installing the BAM Server on the Java Method Server ...................................25


Installing BAM on the Java Method Server using the installer ..............................25
Starting the Java Method Server .......................................................................26
Stopping the Java Method Server......................................................................27
Recommended JBoss application server parameters settings .............................27
Changing the JBoss application server parameters.............................................28
Post-installation guidelines................................................................................28
Troubleshooting BAM server installation on Java Method Server .........................29

Chapter 4

Installing the BAM Server on Red Hat JBoss Application Server ...................31
Overview of installing BAM on Red Hat JBoss....................................................31
Creating BAM database objects manually ..........................................................31
Creating Repository objects manually ................................................................32
Preparing the BAM server WAR file for deployment ............................................33
Enabling DFC connections to the Repository......................................................34
Specifying BAM database connection parameters ..............................................35
Modifying DFC session properties .....................................................................36
Modifying the location of log files .......................................................................36

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Table of Contents

Deploying the BAM application on the JBoss application server...........................37


Recommended JBoss application server parameters settings .............................37
Changing the JBoss application server parameters.............................................37
Post-installation guidelines................................................................................38
Chapter 5

Installing the BAM Server on Apache Tomcat Application Server ..................39


Overview of installing BAM on Apache Tomcat ...................................................39
Creating BAM database objects manually ..........................................................39
Creating Repository objects manually ................................................................40
Preparing the BAM server WAR file for deployment ............................................41
Enabling DFC connections to the Repository......................................................42
Specifying BAM database connection parameters ..............................................43
Modifying DFC session properties .....................................................................43
Modifying the location of log files .......................................................................44
Deploying the BAM application on the Tomcat application server .........................44
Recommended Tomcat application server parameters settings............................45
Changing the Tomcat application server parameters ...........................................45
Post-installation guidelines................................................................................45

Chapter 6

Installing the BAM Server on Oracle Weblogic Application Server ................47


Overview of installing BAM on Oracle WebLogic ................................................47
Creating BAM database objects manually ..........................................................47
Creating Repository objects manually ................................................................48
Preparing the BAM server WAR file for deployment ............................................49
Enabling DFC connections to the Repository......................................................50
Specifying BAM database connection parameters ..............................................50
Modifying DFC session properties .....................................................................51
Modifying the location of log files .......................................................................52
Creating an external configuration folder ............................................................52
Deploying the BAM application on the WebLogic application server .....................53
Recommended WebLogic application server parameters settings........................54
Post-installation guidelines................................................................................54

Chapter 7

Installing the BAM Server on IBM WebSphere Application Server .................55


Overview of installing BAM on WebSphere ........................................................55
Creating BAM database objects manually ..........................................................55
Creating Repository objects manually ................................................................56
Preparing the BAM server WAR file for deployment ............................................57
Enabling DFC connections to the Repository......................................................58
Specifying BAM database connection parameters ..............................................59
Modifying DFC session properties .....................................................................60
Modifying the location of log files .......................................................................60

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Table of Contents

Configuring the WebSphere application server ...................................................60


Deploying the BAM application on the WebSphere application server ..................61
Generating a new Java keystore file ..................................................................63
Recommended IBM WebSphere application server parameters settings ..............63
Post-installation guidelines................................................................................63
Chapter 8

Installing the BAM Server on Oracle Application Server ................................65


Overview of installing BAM on Oracle application servers ...................................65
Creating BAM database objects manually ..........................................................65
Creating Repository objects manually ................................................................66
Preparing the BAM server WAR file for deployment ............................................67
Enabling DFC connections to the Repository......................................................68
Specifying BAM database connection parameters ..............................................69
Modifying DFC session properties .....................................................................69
Modifying the location of log files .......................................................................70
Deploying the BAM application on the Oracle application server..........................70
Recommended Oracle 10g application server parameters settings ......................71
Post-installation guidelines................................................................................72

Chapter 9

Installing the BAM Server on Sun Application Servers ..................................73


Overview of installing BAM on Sun application servers .......................................73
Creating BAM database objects manually ..........................................................73
Creating Repository objects manually ................................................................74
Preparing the BAM server WAR file for deployment ............................................75
Enabling DFC connections to the Repository......................................................76
Specifying BAM database connection parameters ..............................................77
Modifying DFC session properties .....................................................................78
Modifying the location of log files .......................................................................78
Deploying the BAM application on the Sun Application Servers ...........................78
Recommended Sun application server parameters settings ................................79
Post-installation guidelines................................................................................79

Chapter 10

Configuring Business Activity Monitor ..........................................................81


Overview of configuration..................................................................................81
Configuring connection settings.........................................................................81
Activating process monitoring............................................................................82

Chapter 11

Installing Process Reporting Services ...........................................................83


Overview of PRS and Crystal Reports installation...............................................83
PRS Client system requirements .......................................................................83
Installing the Process Reporting Services Client .................................................84
Logging in to PRS ............................................................................................85
Installing Crystal Reports ..................................................................................85

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Table of Contents

I18N Notes ......................................................................................................86


Chapter 12

Installing the Preconfigured Dashboards .......................................................87


Overview of preconfigured dashboard installation ...............................................87
Prerequisites for installing the preconfigured dashboard .....................................87
Installing the preconfigured dashboards.............................................................88

Chapter 13

Upgrading Business Activity Monitor from 6.5 to 6.5 SP1 ..............................89


Overview of upgrading from BAM version 6.5 to 6.5 SP1 ....................................89
Upgrading BAM Repository and BAM database..................................................89

Chapter 14

Upgrading Business Activity Monitor from 6.5 SP1 to 6.5 SP2.......................91


Overview of upgrading from BAM version 6.5 SP1 to 6.5 SP2 .............................91
Upgrading BAM Repository and BAM database..................................................91

Chapter 15

Upgrading Business Activity Monitor from 6.5 SP2 to 6.6 ..............................93


Overview of upgrading from BAM version 6.5 SP2 to 6.6 ....................................93
Upgrading BAM Repository and BAM database..................................................93

Chapter 16

Upgrading Business Activity Monitor from 6.6 to 6.7 .....................................95


Overview of upgrading from BAM version 6.6 to 6.7............................................95
Upgrading BAM Repository and BAM database..................................................95

Chapter 17

Upgrading BAM Artifacts................................................................................97


Upgrading BAM artifacts from version 6.5 and 6.5 SP1 to version 6.6 ..................97
Upgrading BAM artifacts from version 6.5 SP2 to version 6.6 ..............................98
Upgrading BAM artifacts from version 6.6 to version 6.7 .....................................99
Multi-drill-down feature work around when upgrading from TaskSpace 6.6 to
6.7 ...............................................................................................................99

Chapter 18

Installation Verification................................................................................. 101


Installation Verification .................................................................................... 101

Chapter 19

Uninstalling BAM.......................................................................................... 103


Manually uninstalling BAM .............................................................................. 103

Chapter 20

Clustering Business Activity Monitor........................................................... 105


Clustering Business Activity Monitor ................................................................ 105

Chapter 21

Troubleshooting ........................................................................................... 107


Dropping object types and tables from a BAM database ................................... 107

Appendix A

Working with WAR and EAR Files ................................................................ 109

Appendix B

Working with the data-loader.properties file................................................. 111

Appendix C

Externalizing BAM configuration files .......................................................... 115

Appendix D

Security ........................................................................................................ 117

Working with WAR and EAR Files........................................................................................ 109


Working with the data-loader.properties file ........................................................................ 111
Externalizing BAM configuration files ................................................................................. 115
Security ............................................................................................................................... 117

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Preface
Purpose of the manual
This manual contains information and instructions required to create a Business Activity Monitor
(BAM) database on Oracle, MS SQL, or DB2. It also includes instructions for installing the BAM
server on:
Content Server with the JBoss application server in a Windows environment using the BAM
Engine Installer (automatic installation)
Red Hat JBoss application server (manual installation)
Apache Tomcat application server (manual installation)
Oracle WebLogic application server (manual installation)
IBM WebSphere application server (manual installation)
Oracle application server (manual installation)
Sun application server (manual installation)
The final chapters of this guide are dedicated to installing the Process Reporting Services (PRS)
reporting application and the preconfigured dashboards. This installation guide describes decisions
to make and requirements to meet before BAM is installed.

Intended audience
This manual is intended for the person installing the BAM software that includes the BAM server,
the Process Reporting Services Client, and the preconfigured dashboard. Typically, a system
administrator installs the software.

Important recommendation for users


Before installing the BAM server, it is recommended that users installing BAM, have a general
understanding of the following Documentum products:
Content Server
Composer
Process Builder
TaskSpace

Documentation conventions
This guide uses the following conventions:
Convention

Description

>

The angle bracket is used to separate menu options in a


progression of menu choices the user must select in a graphical
user interface (GUI). For example, File > Save As means,
select the File menu and then choose the Save As option.

code

All sample code is represented in Courier New font.

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Preface

Convention

Description

user interface label

Bold and small text is used to represent a user interface label.


For example, menus, buttons, and pages.

[]

Square brackets are used to enclose place-holder folder names,


which you can substitute with valid folder names.

{}

Curly brackets are used to enclose at least one required item.

\foldername_or_filename

Bold text separated by the forward slash is used to represent


the name of a file or file path.

Note: Most of the path strings defined in this document


are depicted in the MS Windows style (with a backslash
(\) in path strings), while the forward slash (/) is also
used in some names of files and paths. However, if the
backslash (\) is used in a non-Windows path, it does not
imply that the paths are incorrect.
<>

Angle brackets are used to enclose a variable name for which


you must provide a value.

%%

Percentage characters are used in the Windows environment


to enclose a variable or directory to obtain the value of the
variable or directory.

${ }

Curly brackets preceded by the $ sign are used in the UNIX


environment to enclose a variable or directory to obtain the
value of the variable or directory.

Revision history
This section contains a description of this documents revision history.
Table 2

Revision history

Revision Date

Description

April 2011

Initial Publication

Support Information
EMC Documentums technical support services and policies are available at the EMC Powerlink
website (http://powerlink.emc.com). To download the Customer Guide to EMC Software Support
Services from Powerlink, select Support > Request Support > Software Customer Guide and
Offerings.
Note: You must register online at Powerlink before using it.

Related documentation
This manual forms part of a documentation suite designed to support those who install, configure,
and use Business Activity Monitor. In addition to this manual, the documentation set for Business
Activity Monitor includes:
Documentum Content Server Installation Guide, version 6.7
Documentum Business Activity Monitor Implementation Guide, version 6.7

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Preface

Documentum Business Activity Monitor Release Notes, version 6.7


Documentum Administrator Deployment Guide, version 6.7
Documentum Process Builder Installation Guide, version 6.7
Documentum Forms Builder Installation Guide, version 6.7
Documentum Process Engine Installation Guide, version 6.7
Documentum TaskSpace Deployment Guide, version 6.7
Documentum Composer User Guide, version 6.7
You can go to the Documentation area of the EMC Powerlink website (http://powerlink.emc.com )
to download product documentation. To locate product documentation, select Support > Technical
Documentation and Advisories > Software ~ D ~ Documentation > Documentum <First letter
of your product>. Select your product and click the software version number in the Left pane of
the page that is displayed.

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Preface

10

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Chapter 1
Overview of Business Activity Monitor
This chapter discusses the following:

Prerequisites for installing the BAM server

Overview of the BAM installation procedure

Downloading the BAM product installation files

Unpacking BAM product installation files

Installing BAM without a connection to the Internet

Installing the BAM server

Installing the Process Reporting Services Client and Crystal Reports

Installing the preconfigured dashboard

Prerequisites for installing the BAM server


This section lists the prerequisites to prepare the Documentum environment for installing the BAM
server. For information about the BAM server system requirements, see the Business Activity Monitor
6.7 Release Notes. For every installation, log on to the operating system with a user account that has
administrative rights on the operating system, such as the Administrator user.
Install the following Documentum products:
Content Server
Process Builder
Forms Builder
Process Engine
Note: Process Engine must be installed before the TaskSpace DAR is installed.
TaskSpace
Note: TaskSpace must be installed using the DAR and not the DocApp.
Prepare and size a BAM database instance before the BAM server is installed.
Note: The Release Notes document of the various Documentum products, contains a complete list
of Environment and System Requirements. For more information, see the Release Notes document
of the relevant product.
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

11

Overview of Business Activity Monitor

Overview of the BAM installation procedure


The BAM installation process involves:
1. Unpacking WAR Files, page 109.
2. Installing a database, creating a database user, granting appropriate access rights to the database
user, and sizing the database. You can install one of the following databases: MS SQL, Oracle, or
DB2. For instructions see, Preparing the Microsoft SQL Server database, page 18, Preparing the
Oracle database, page 19, or Preparing the DB2 database, page 20. For information about database
sizing, see Sizing the BAM database, page 23.
3. Installing the BAM server, page 14.
4. Installing the Process Reporting Services Client, page 84.
5. Installing the preconfigured dashboards, page 88.

Downloading the BAM product installation files


The following modules/files comprise the contents of this release:
Documentum Business Activity Monitor Product, Version 6.7 (zip), which includes:
BAM Data Loader
BAM Installer folder (requires local Content Server) containing the BAM_Installer_
JBoss_win.zip file. The preconfigured dashboard DAR is located in this ZIP file.
BAM Server folder with the following contents:
bam-server.war
Websphere folder with the xalan.jar and xercesImpl.jar files
Oracle folder containing a bam-server-oc4j-10.1.3.3.war file
PRS folder containing the PRS-win32.win32.x86.zip file
Properties file that contains BAM product version information
Documentum Business Activity Monitor Supplemental Files, Version 6.7 (zip), which includes:
Dashboard Style Utility: Contains a utility that is used to customize the look and feel of a BAM
dashboard
BAM Dashboard Sizing Calculator: Contains a spreadsheet that is used to calculate the space
allocated to the BAM database
WebSphere 7.0.0.7 JARs: Contains JAR files used when deploying BAM on WebSphere
Application Server version 7.0.0.7
Hotfix folders and files
Crystal Reports 2008 (zip): Contains one seat license of Crystal Reports
Crystal Reports 2008 License Key (txt)
Documentum Business Activity Monitor Release Notes, Version 6.7 (pdf)
Documentum Business Activity Monitor Installation Guide, Version 6.7 (pdf)
Documentum Business Activity Monitor Implementation Guide, Version 6.7 (pdf)
12

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Overview of Business Activity Monitor

Download the following BAM product installation files from the Powerlink website
(http://powerlink.emc.com) into a local folder:
bam-product.zip: Contains installation files for all supported application servers, BAM
server, Process Reporting Services, BAM Data Loader components, and the preconfigured
dashboards. The PreConfiguredDashboard.dar is located in: bam-product.zip/BAM
Installer/BAM_Installer_JBoss_win.zip/dars.jar/.
Crystal_Designer_XI_R2_SP2.zip: Contains the Crystal Reports Designer XI R2 SP2 product
installer. Unpack the zipped file, which contains one seat of Crystal Reports.
CR_Designer_license_key.txt: Contains the Crystal Reports Designer License Key. Download this
file into the same folder where you downloaded Crystal_Designer_XI_R2_SP2.zip.
bam-product-supplemental_files.zip: Contains the following Business Activity Monitor
supplemental files:
Dashboard Style Utility installation files are available in the Dashboard Style Utility folder of
the bam-product-supplemental_files.zip file. This utility can be used to customize the look and
feel of a BAM dashboard.
BAM Dashboard Sizing Calculator spreadsheet is available in the BAM Database Sizing
Calculator folder of the bam-product-supplemental_files.zip file. This spreadsheet can be used
to calculate the space that must be allocated to the BAM database.
WebSphere\7.0.0.7\Required jars: Contains 5 JAR files that are used when deploying BAM on
WebSphere Application Server version 7.0.0.7.
You can now unpack the bam-product.zip file into the relevant folder.

Unpacking BAM product installation files


This procedure guides you in unpacking the BAM product installation files you download from the
EMC Download Center.
To unpack the BAM product installation files:
1. Create [Temporary BAM setup folder] (for example, C:\Temp) on the local machine.
2. Access the folder where you downloaded the bam-product.zip file.
3. Unpack bam-product.zip into [Temporary BAM setup folder] (for example, C:\Temp).

The following BAM setup folder structure is created in [Temporary BAM setup folder] (for
example, under the C:\Temp folder):

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

13

Overview of Business Activity Monitor

Installing BAM without a connection to the


Internet
The Business Activity Monitor installer might raise a connection error message if a connection to the
Internet is unavailable or is extremely slow. The issue occurs during the installation of Business
Activity Monitor using Installer on the Windows OS when there is no connection to the internet.
To install BAM without a connection to the Internet:
1. Stop Documentum Java Method Server.
2. Create a backup copy of:
%DOCUMENTUM%\jboss4.2.0\server\DctmServer_MethodServer\deploy\
ServerApps.ear\DmMethods.war\WEB-INF\web.xml.
3. Open the following file for edit:
%DOCUMENTUM%\jboss4.2.0\server\DctmServer_MethodServer\deploy\
ServerApps.ear\DmMethods.war\WEB-INF\web.xml.
4. Remove the DOCTYPE declaration line:<!DOCTYPE web-app PUBLIC
"-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">.

5. Save the web.xml file.


6. Install Business Activity Monitor.
7. Start Documentum Java Method Server.

Installing the BAM server


After downloading and unpacking the product installation files, you can proceed with one of the
following tasks:
Installing the BAM server using the BAM Engine Installer on the Java Method Server Use
the BAM Engine installer to install the BAM server and the PRS Client on the Java Method Server
on which the Content Server with the JBoss application server is installed on a Windows platform.
14

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Overview of Business Activity Monitor

The installer will also install the preconfigured dashboard. For instructions, see Installing BAM on
the Java Method Server using the installer, page 25
Installing the BAM server manually Use this option to manually install the BAM server on a
machine where the JBoss, Tomcat, WebLogic, or WebSphere application server is installed. In this
case, the BAM server connects to the Content Server and BAM database that may be on different
machines. For more information, see the instructions relevant to your application server:
Overview of installing BAM on Red Hat JBoss, page 31
Overview of installing BAM on Apache Tomcat, page 39
Overview of installing BAM on Oracle WebLogic, page 47
Overview of installing BAM on WebSphere, page 55
Overview of installing BAM on Oracle application servers, page 65
Overview of installing BAM on Sun application servers, page 73
Note: For information about the platforms and application servers on which the BAM server can be
installed, see the Business Activity Monitor Release Notes.

Installing the Process Reporting Services Client


and Crystal Reports
After installing the BAM server, you can install the Process Reporting Services Client and Crystal
Reports. For instructions, see Overview of PRS and Crystal Reports installation, page 83.

Installing the preconfigured dashboard


If you installed the BAM server on an application server manually, then install the preconfigured
dashboard manually. For instructions, see Overview of preconfigured dashboard installation, page 87.

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

15

Overview of Business Activity Monitor

16

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Chapter 2
Preparing the Database
This chapter discusses the following:

Overview of preparing the BAM database

Preparing the Microsoft SQL Server database

Preparing the Oracle database

Preparing the DB2 database

Sizing the BAM database

Overview of preparing the BAM database


Prepare and size a database instance before you install the BAM server. This chapter discusses the
process of preparing the database so that you can install the Business Activity Monitor (BAM) server.
Create the required database schema before running the database installation script.
The following databases are supported:
Microsoft SQL Server
Oracle
DB2
For information about the BAM database requirements, see the Business Activity Monitor 6.7 Release
Notes.
After you have created the database, perform the following steps to prepare the BAM database
(Oracle/MS SQL/DB2):
Create a Tablespace. For instructions, see the Preparing the Microsoft SQL Server database, page
18, Preparing the Oracle database, page 19, or Preparing the DB2 database, page 20 section.
Create a database user. For instructions, see the Preparing the Microsoft SQL Server database, page
18, Preparing the Oracle database, page 19, or Preparing the DB2 database, page 20 section.
Grant appropriate access rights to the database user. For instructions, see the Preparing the Microsoft
SQL Server database, page 18, Preparing the Oracle database, page 19, or Preparing the DB2
database, page 20 section.
Size the database. For information, see the Sizing the BAM database, page 23 section.
The following tasks must be completed before installing the BAM server:
1. Obtain the following details required to configure the BAM database connection: Database Server
Host name, Database Name (SID in Oracle), User Name, and Password.
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

17

Preparing the Database

2. Install the required database, prepare it, and ensure that it is running. If these tasks are not
performed, the installation of the BAM server cannot be completed. It is recommended that you do
not install the BAM server on the same machine as the database server. Therefore, there must be
access from the installation machine to the database by way of a TCP/IP connection.
Note: The BAM server uses its own database to process and maintain monitoring information. The
server does not require the database client for its operations. The server uses the JDBC driver for
database operations.

Preparing the Microsoft SQL Server database


This section guides you through the process of preparing the MS SQL database. Before installing the
BAM server, prepare the MS SQL database for use with the BAM server. Complete the following
procedure to create the required SQL Server database, before running the database installation script.
To prepare the Microsoft SQL Server database:
1. Prepare the database by performing the following steps:

a. Set the data file size to 500 MB (default recommended sizing).


b. Set the transaction log size to 500 MB (default recommended sizing).
Note: Set the transaction log file to auto-growth because it grows to a large size. Check the
size of the log file periodically, and if it gets too large, back it up and then truncate it.
2. Create a login.

a. Create a login for BAM.


b. Use Microsoft SQL Server authentication and set password.
3. Associate the role db owner with the BAM user in the new database. For SQL Server 2005 and
higher, set the default schema of the user to dbo.
To ensure best performance, use the following initialization parameters while creating the BAM
database.
Table 3

Microsoft SQL Server Parameters

Parameter name

Value

Security

SQL Server And Windows Authentication

Connections

Query Time-Out = 0 (unlimited)


Maximum Concurrent User connections = 0 (unlimited)

Attributes

Close cursor on Commit = V (enable)


ANSI Warning = V (enable)
ANSI padding = V (enable)
ANSI nulls = V (enable)

18

Autostart policies when the


operating system starts

Autostart SQL Server (enable) Autostart SQL Server Agent (enable)

Network

TCP/IP

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Preparing the Database

Parameter name

Value

Server Collation

Case-sensitive

MS SQL collation Code page

To avoid loss of data, the BAM database collation and the Content
Server database collation must be identical. In addition, the BAM
database collation and BAM database instance collation must be
identical. Having the same collation is required for the BAM server
to function properly on an MS SQL database.

Preparing the Oracle database


This task guides you through the process of preparing the Oracle database. Complete the following
procedure to create the required Oracle schema before running the database installation script.
Note: To support multi-byte languages the Character set must be AL32UTF8.
To prepare the Oracle database:
1. Verify that the Oracle server is installed and running.
Note: Perform steps 2 and 3 if you have a production installation. Alternatively, skip to step 4 if
you have a lightweight or non-production installation.
2. Create an Oracle instance.
The initial recommended Oracle tablespace sizes are:
User table space approximately 500 MB
System table space approximately 700 MB
Undo table space to 1 GB
Temp table space to 1 GB
Index table space to 500 MB
3. Initialize schema parameters using the Oracle Settings table found at the end of this section.
4. Create an Oracle user and password pair.
5. Grant the following access to the new user:
For Oracle 9i databases:
Grant CONNECT
Grant RESOURCE
Grant CREATE SEQUENCE
For Oracle 10g databases:
Grant CONNECT
Grant RESOURCE
Grant CREATE VIEW
Grant CREATE SEQUENCE
Table 4

Oracle Parameters

Parameter Name

Value

Comment

DB_BLOCK_SIZE

8,192

Must be set during schema creation

DB_CACHE_SIZE

100,000,000

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

19

Preparing the Database

Parameter Name

Value

Comment

OPTIMIZER_MODE

CHOOSE

Note: This setting is crucial.

SHARED_POOL_SIZE

50,000,000

LOG_CHECKPOINT_INTERVAL 0
DML_LOCKS

1,000

PROCESSES

500

LOG_BUFFER

655,360

OPEN_CURSORS

2,000

SORT_AREA_SIZE

5,000,000

MAX_DUMP_FILE_SIZE

10,240

DB_FILES

121

TIMED_STATISTICS

TRUE

Operating system dependent

Note: The database administrator should periodically monitor the database and modify the
parameters based on size changes.

Preparing the DB2 database


This section guides you through the process of preparing the DB2 database. It also includes a
troubleshooting section on the DB2 database. Complete the steps listed in the following table to create
the required DB2 schema before running the database installation script. The Character set must be set
to UTF8 for multi-byte language support.
To prepare the DB2 database:
1. Verify that the DB2 Server is installed.
2. Create database by using the Control Center. By default, three tablespaces are created system,
user, and temporary each with a page size equal to 4 KB. In addition, a default pool is created
with a page size of 4 KB.
CREATE DATABASE BAM
ON C: USING CODESET UTF-8 TERRITORY US
COLLATE USING
SYSTEM CATALOG TABLESPACE
MANAGED BY SYSTEM
USING ( C:\DB2\BAM\catalog_tables )
EXTENTSIZE 16
PREFETCHSIZE 16
OVERHEAD 10.50
TRANSFERRATE 0.14
USER TABLESPACE
MANAGED BY SYSTEM
USING ( C:\DB2\BAM\user_tbs_4kb )
EXTENTSIZE 16
PREFETCHSIZE 16
OVERHEAD 10.50
TRANSFERRATE 0.14

20

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Preparing the Database

TEMPORARY TABLESPACE
MANAGED BY SYSTEM
USING ( C:\DB2\BAM\temp_tbs_4kb )
EXTENTSIZE 16
PREFETCHSIZE 16
OVERHEAD 10.50
TRANSFERRATE 0.14@

3. Add two buffer pools. The first buffer pool must support page size 16 KB. The second buffer
pool must support 32 KB.
name=POOL16 (this can be
changed)
SIZE = 250 (this can be
changed) page size = 16K
(this cannot be changed)
The second buffer pool
must support 32 KB.
name=POOL32 (this can be
changed)
SIZE = 250 (this can be
changed) page size = 32K
(this cannot be changed)

Example: CREATE BUFFERPOOL POOL16 IMMEDIATE SIZE 250 PAGESIZE 16


K@
4. Create 2 new User Tablespaces with page size 16 KB and 32 KB.
CREATE REGULAR TABLESPACE USER_TBS_16
PAGESIZE 16 K
MANAGED BY SYSTEM
USING (C:\DB2\BAM\user_tbs_16kb ) EXTENTSIZE 4
OVERHEAD 10.5
PREFETCHSIZE 4
TRANSFERRATE 0.14
BUFFERPOOL POOL16 @
CREATE REGULAR TABLESPACE USER_TBS_32
PAGESIZE 32 K
MANAGED BY SYSTEM
USING (C:\DB2\BAM\user_tbs_32kb ) EXTENTSIZE 4
OVERHEAD 10.5
PREFETCHSIZE 4
TRANSFERRATE 0.14
BUFFERPOOL POOL32 @"

5. Create a User Temporary Tablespace with page size 4 KB.


CREATE USER TEMPORARY TABLESPACE
USER_TMP_4 PAGESIZE 4 K
MANAGED BY SYSTEM
USING (C:\DB2\BAM\user_temp_tbs_4kb )

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

21

Preparing the Database

EXTENTSIZE 4
OVERHEAD 10.5
PREFETCHSIZE 4
TRANSFERRATE 0.14
BUFFERPOOL IBMDEFAULTBP @

6. Create a System Temporary Tablespace with page size 32 KB.


CREATE SYSTEM TEMPORARY TABLESPACE
TEMPSPACE_32
PAGESIZE 32 K
MANAGED BY SYSTEM
USING (C:\DB2\BAM\temp_tbs_32kb )
EXTENTSIZE 4
OVERHEAD 10.5
PREFETCHSIZE 4
TRANSFERRATE 0.14
BUFFERPOOL POOL32 @

7. Create a user in the operating system. Then add this user to the list of Database Users.
8. Grant the following authorization to the new user:
connect to database
create tables
create schemas implicitly
create external routines
register routines to execute in database
managers process
In addition, grant the use of the User Tablespaces with 4KB and 16KB and 32-KB page sizes
and User Temporary Tablespace with page size 4 KB.

Example:
GRANT CREATETAB,CONNECT,
CREATE_NOT_FENCED_ROUTINE,IMPLICIT_SCHEMA,
CREATE_EXTERNAL_ROUTINE ON DATABASE TO
USER ALEX@
GRANT USE OF TABLESPACE USERSPACE1
TO USER ALEX @

9. Update SQL statement heap (STMTHEAP) to be equal to at least 10240.

Example: db2 update db cfg using STMTHEAP 10240


10. Update application control heap size configuration parameter to be equal at least 512.

Example: update db cfg using app_ctl_heap_sz 512


11. You can now create the BAM database tables.
Note: A database administrator should periodically run a RUNSTATS command on all tables and
indexes in the BAM database. This command provides meaningful database statistics.

22

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Preparing the Database

Sizing the BAM database


As part of the process of preparing a database, it is important that you set the size of the database
accurately. This ensures adequate space in the database to accommodate all historical data. Failure to
set enough space may result in loss of data or problems with the execution of the Business Activity
Monitor.
The size of the Business Activity Monitoring database depends on the number of processes that must
be monitored, the frequency of their execution, the amount of business data that is tracked, and the
duration for which the data must be retained before it is purged.
The BAM Database Sizing Calculator is a spreadsheet that can help to accurately estimate the database
size. For instructions about downloading the spreadsheet, see:
Downloading the BAM product installation files, page 12
Unpacking BAM product installation files, page 13
In the Input Page sheet of the spreadsheet, enter the values that reflect the expected load of the
application. The Output Summary Page provides you with database size measures.

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

23

Preparing the Database

24

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Chapter 3
Installing the BAM Server on the Java
Method Server
This chapter discusses the following:

Installing BAM on the Java Method Server using the installer

Starting the Java Method Server

Stopping the Java Method Server

Recommended JBoss application server parameters settings

Changing the JBoss application server parameters

Post-installation guidelines

Troubleshooting BAM server installation on Java Method Server

Installing BAM on the Java Method Server


using the installer
This section provides instructions on how to use the BAM Engine installer to install the BAM server
on the Java Method Server. The installer is used for installing the BAM server and the PRS client
on the same machine as the Content Server on the Windows platform. You must have the Windows
administrator access rights to perform the BAM server installation. Prepare and size the database
instance before installing the BAM server.
Note: The BAM installer is used to create a database, install the BAM server, install the preconfigured
dashboards, and install PRS.
Note: Documentum administrator credentials are used to connect from the BAM server to the
repository.
To install BAM on the Java Method Server using the installer:
1. Create a temporary folder called [Temporary BAM Installer folder].
2. Unpack the BAM_Installer_JBoss_win.zip file into [Temporary BAM Installer folder].
All the contents of the .zip file are unpacked into the folder.
3. Access the [Temporary BAM Installer folder]\BAM Installer folder.
4. Run bamWinSuiteSetup.exe. The BAM Engine Installer wizard appears within a minute.
5. Select the Business Activity Monitoring product.
6. (Optional) Select Process Reporting Services, if you want to install PRS Client also.
7. Click Next.
The Welcome page is displayed.
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

25

Installing the BAM Server on the Java Method Server

8. Click Next.
The License Agreement page is displayed.
9. Select I accept the terms of the license agreement option and click Next.
The next page of the Documentum BAM Engine Installer wizard displays the details of the
repository that the installer updates.
10. Select a repository, and specify the user credentials.
Note: The user name you enter is the same as the owner of the Documentum installation. If you
specify a different user name, the BAM installation fails.
11. Click Next.
12. Specify the BAM database connection parameters.
The installer validates the database connection information specified, and displays an error
message when it is unable to establish connection with the BAM database.
13. Click Next.
The Products Summary page listing all products and components is displayed.
14. Click Next to start the installation.
The BAM server and the preconfigured dashboard DAR are installed. After the installation
has completed successfully, the last page of the Documentum BAM Engine Installer wizard is
displayed.
15. Click Finish to exit the Documentum BAM Engine Installer wizard.
16. Restart the Documentum Java Method Server. For instructions, see Starting the Java Method
Server, page 26 and Stopping the Java Method Server, page 27.

The BAM Server 6.7 installation program creates the following directory structure under the
[documentum.home]\bam\ folder:

Starting the Java Method Server


When you first install the Content Server installation, the JBoss application server is started
automatically. However, starting and stopping a Content Server in the installation does not
automatically start or stop the JBoss application server. The application server hosts one or more Java
applications or processes. In a Content Server installation, the method server hosts, for example, the
Java Method Server, ACS server, and the DmMail application.
26

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Installing the BAM Server on the Java Method Server

To start the Java Method Server:


1. Navigate to [JBoss server root]\server.
2. Execute startMethodServer.cmd.
3. Alternatively, start the Windows service for the server instance.
For the Java Method Server, and the server instance hosting the Java Method Server, the service
name is Documentum Java Method Server. Starting that service is equivalent to executing
startMethodServer.cmd.

Stopping the Java Method Server


Use the following procedure to stop the application server. Stopping the server stops all applications
running within it.
To stop the Java Method Server:
1. Navigate to [JBoss server root]\server.
2. Execute stopMethodServer.cmd.
3. Alternatively, stop the Windows service for the server instance.
For the Java Method Server, and the server instance hosting the Java Method Server, the service
name is Documentum Java Method Server. Stopping that service is the same as executing
stopMethodServer.cmd.

Recommended JBoss application server


parameters settings
Change the JBoss application server parameters as follows:
Initial Java heap size: 512 m
Maximum Java heap size: 1024m
Java threads stack size: 128k
Initial size for the permanent generation heap: 128m
Maximum size for the permanent generation heap: 256m
Initial size of new generation pool: 128 m
Maximum size of new generation pool: 384m
Use parallel GC:
Number of threads used by parallel GC: 20

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

27

Installing the BAM Server on the Java Method Server

Changing the JBoss application server


parameters
1. Access one of the following folders:
Windows: [JBoss server root]\bin\
UNIX/Linux: [JBoss server root]/bin/
2. Modify run.bat (Windows) or run.sh (on UNIX/Linux).
For example, use the following settings for Sun Java 5:
set JAVA_OPTS=-server -XX:+UseParallelGC -Xms1024m -Xmx1024m
-XX:NewSize=128m -XX:MaxNewSize=256m -XX:MaxPermSize=256m

Post-installation guidelines
Checking for installation errors
Log files are available in the Documentum installation folder. For example, the log files are available
in the C:\Program Files\Documentum\bam\bin and C:\Program Files\Documentum\bam\log folders.
It is recommended that you check for any installation errors in the following logs after the BAM
server is installed successfully:
run-api.log
run-dql.log
sql-loader.log
create-repository.log
If the logs contain errors, contact EMC Technical Support.

Changing the default host and port from TaskSpace to


point to the BAM server URL
The default port for Red Hat JBoss AS 4.2.3 is 9080 (for this installation on the Java Method Server).
Ensure that the BAM server port number is configured in the BAM Port field of the Administration
tab of TaskSpace to point to port 9080.
If the BAM server and TaskSpace are not installed on the same physical machine, change the BAM
Host URL from localhost to the IP address of the BAM server machine. This procedure is completed
in the Administration tab of TaskSpace.
For instructions, see the Configuring connection settings section of the Business Activity Monitor
Implementation Guide.

28

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Installing the BAM Server on the Java Method Server

Troubleshooting BAM server installation on


Java Method Server
If the internet connection is unavailable or slow while installing the BAM Engine on Windows, the
BAM installer displays a connection error message.
To work around this problem:
1. Stop the Documentum Java Method Server, if it is running.
2. Create a backup copy of the web.xml file available in the following
path:%DOCUMENTUM%\jboss4.2.0\server\DctmServer_MethodServer\deploy\ServerApps.ear\
DmMethods.war\WEB-INF\.
3. Open the web.xml file available in the following path for
editing:%DOCUMENTUM%\jboss4.2.0\server\DctmServer_MethodServer\deploy\ServerApps.ear\
DmMethods.war\WEB-INF\.
4. Remove the following DOCTYPE declaration line in the file, and save the file:<!DOCTYPE
web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">.
5. Install the BAM server using the BAM Engine installer.
6. Start the Documentum Java Method Server, if it is required.

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

29

Installing the BAM Server on the Java Method Server

30

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Chapter 4
Installing the BAM Server on Red Hat
JBoss Application Server
This chapter discusses the following:

Overview of installing BAM on Red Hat JBoss

Creating BAM database objects manually

Creating Repository objects manually

Preparing the BAM server WAR file for deployment

Enabling DFC connections to the Repository

Specifying BAM database connection parameters

Modifying DFC session properties

Modifying the location of log files

Deploying the BAM application on the JBoss application server

Recommended JBoss application server parameters settings

Changing the JBoss application server parameters

Post-installation guidelines

Overview of installing BAM on Red Hat JBoss


This chapter describes the process of installing the BAM server manually on a machine where only the
Red Hat JBoss application server is installed. This installation assumes that the Content Server and
BAM database are installed on another machine or on different machines. Installing the BAM server
requires the completion of the following tasks: proper creation of the repository and database objects,
and updating the BAM configuration files. Finally, this chapter includes post-installation guidelines.
You must have the access rights of an administrator to perform the BAM server installation. In
addition, use administrator credentials to connect from BAM server to the repository.
Note: For information about the platforms and application servers on which the BAM server can be
installed, see the Business Activity Monitor Release Notes.

Creating BAM database objects manually


Use the BAM Data Loader utility to create the BAM database and Repository objects (tables, types,
shipping data) manually, before you install the BAM server. You can also use this utility to clean the
BAM Repository and database objects when there are Repository- or database-related errors. This
utility is installed as part of the BAM server installer for JBoss and also resides in bam-product.zip.
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

31

Installing the BAM Server on Red Hat JBoss Application Server

To create BAM database objects:


1. Access one of the following folders:
Windows: [Temporary BAM setup folder]\BAM Data Loader\bin\
UNIX/Linux: [Temporary BAM setup folder]/BAM Data Loader/bin/
2. Execute the following batch/shell files and when prompted, provide the BAM database connection
parameters on the command line:
For Microsoft SQL-Server:
Windows: create-db-objects-mssql.cmd
UNIX/Linux: create-db-objects-mssql.sh
For DB2 database:
Windows: create-db-objects-db2.cmd
UNIX/Linux: create-db-objects-db2.sh
For Oracle database:
Windows: create-db-objects-oracle.cmd
UNIX/Linux: create-db-objects-oracle.sh

The database connection parameters you must specify are as follows:


JAVA_HOME: Enter the Java runtime home path (Java JRE must exist on your computer).
For example: C:\Program Files\Java\jre1.6.
database user: Enter the name of the BAM database owner.
database password: Enter the password of the BAM database owner.
database host: Enter the host name or IP address of the database server.
database port: Enter the port of the database server.
database name: For Oracle: Enter the SID. For DB2 and SQL-Server: Enter the database
name.
CAUTION: When executing the database creation script you must make sure that the path to
the JRE entered in the command line is valid. If an invalid path is provided the creation script
fails, however, no error is provided in the log file. If you have any doubts about the validity of the
JRE path, check the BAM database to make sure that the objects were created.
3. Verify the results of running the SQL script by viewing the following log file in one of the
specified paths:
Windows: [Temporary BAM setup folder]\BAM Data Loader\log\data-loader.log
UNIX/Linux: [Temporary BAM setup folder]/BAM Data Loader/log/data-loader.log

Creating Repository objects manually


The Repository creation scripts run locally on the Content Server machine. Before executing the
relevant script, copy the [Temporary BAM setup folder]\BAM Data Loader\ folder to the Content
Server machine.
32

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Installing the BAM Server on Red Hat JBoss Application Server

To create the Repository objects:


1. Access one of the following folders:
Windows: [Temporary BAM setup folder]\BAM Data Loader\bin\
UNIX/Linux: [Temporary BAM setup folder]/BAM Data Loader/bin/
2. Run one of the following batch/shell files:
Windows: create-repo-objects.cmd
UNIX/Linux: create-repo-objects.sh
3. When prompted, provide the following Repository connection parameters on the command line:
repository name
login name (repository owner or administrator name)
password
When you run the create-repo-objects command, you get the following outputs:
run-api finished with errorlevel = 0
run-dql finished with errorlevel = 1
This output is normal.
4. Verify the results of running the SQL script by viewing the following log files in the BAM Data
Loader folder:
run-api.log
run-dql.log

Preparing the BAM server WAR file for


deployment
Perform the following procedure to prepare the BAM server WAR file for deployment.
To prepare the BAM server WAR file contents for deployment:
1. Create [Temporary WAR location] and the bam-server.war folder under it.
2. Access one of the following folders:
Windows: [Temporary BAM setup folder]\BAM Server\
UNIX/Linux: [Temporary BAM setup folder]/BAM Server/
3. Unpack the bam-server.war file into the [Temporary WAR location]\bam-server.war\ folder. For
instructions about unpacking the WAR file, see Unpacking WAR Files, page 109.
4. If you are using an Oracle 10 or 11 BAM database, complete the steps below. Otherwise, proceed
to step 5.

a. Delete the ojdbc14.jar file located in bam-server.war\WEB-INF\lib.


b. From the bam-product-supplemental_files.zip file you downloaded from the EMC Download
Center, open bam-product-supplemental_files\Oracle.

c. If you are using JDK 1.5, copy the ojdbc5.jar file to bam-server.war\WEB-INF\lib.
d. If you are using JDK 1.6, copy the ojdbc6.jar file to bam-server.war\WEB-INF\lib.
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

33

Installing the BAM Server on Red Hat JBoss Application Server

5. Complete the following steps if you are deploying BAM on JBoss EAP 5.1:

a. Remove the following files from ..\bam-server.war\WEB-INF\lib:


activation.jar
FastInfoset.jar
jaxb-api.jar
jaxb-xjc.jar
jaxrpc.jar
jaxws-api.jar
jaxws-tools.jar
jsr173_api.jar
jsr181-api.jar
jsr250-api.jar
resolver.jar
saaj-api.jar
xpp3.jar

b. Open bam-product-supplemental_files\JBoss 5.1\CrystalReports.


c. Copy xpp3.jar to bam-server.war\WEB-INF\lib.
6. Modify the dfc.properties file using instructions in Enabling DFC connections to the Repository,
page 34. Perform this procedure before attempting to connect to Documentum repositories.
7. Modify the jdbc-config.xml file using instructions in Specifying BAM database connection
parameters, page 35.
8. Modify the dfc-config.xml file using instructions in Modifying DFC session properties, page 36.
9. Modify the log4j.properties file using instructions in Modifying the location of log files, page 36.
Note: Externalizing BAM configuration files, page 115 is another approach that can be used to
configure the BAM server.

Enabling DFC connections to the Repository


Connection broker values must be entered in dfc.properties before BAM is able to connect with a
Repository.
To enable DFC connections to the Repository:
1. Open the dfc.properties file available in one of the following paths where you unpacked the
WAR file:
Windows: [Temporary WAR location]\bam-server.war\WEB-INF\classes
UNIX/Linux: [Temporary WAR location]/bam-server.war/WEB-INF/classes
2. Perform one of the following tasks:

a. If you are installing the BAM server on the Content Server computer, replace
the first line of the dfc.properties file with the following statement:#include
[documentum_user_dir]\config\dfc.properties.
34

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Installing the BAM Server on Red Hat JBoss Application Server

For example, specify the path to the dfc.properties file as follows: #include
C:\Documentum\config\dfc.properties.
b. If you are installing the BAM server on a computer other than the Content Server computer,
delete or comment the #include statement. Then, specify the required values for the following
parameters:
dfc.docbroker.host[0]=host_name
dfc.docbroker.port[0]=port_number
3. Save and close the dfc.properties file.

Specifying BAM database connection


parameters
BAM database connection parameters entered in jdbc-config.xml enable the BAM server to connect
to the BAM database.
To specify BAM database connection parameters:
1. Open the jdbc-config.xml file available in one of the following paths:
Windows: [Temporary WAR location\bam-server.war\WEB-INF\classes\config\
UNIX/Linux: [Temporary WAR location/bam-server.war/WEB-INF/classes/config/
2. Modify the following BAM database connection parameters with the relevant values by editing
the XML file. You can open the XML file using a standard file editor or an XML Editor. Modify
the following XML element values:
dialect For example, in the case of MS SQL, change <dialect>$C(BAM,
DCTM_BAM_DB_DIALECT)</dialect> to <dialect>mssql</dialect>
URL
driver
username
password
Use the RDBMS Type, Dialect, and Driver Class values specified in the following table, and
specify the Connection URL based on your RDBMS environment:
Table 5

BAM Database connection parameters and values

RDBMS
Type

Dialect

Driver Class

Connection URL

MS SQL

mssql

com.microsoft.com.microsoft.

jdbc:sqlserver://<HOST>:<PORT>;

sqlserver.jdbc.SQLServer
Driver

databasename=<DB.NAME>;
SELECTMETHOD=Cursor

Oracle

oracle

oracle.jdbc.driver.OracleDriver

jdbc:oracle:thin:@<HOST>:
<PORT>:<SID>

DB2

db2

com.ibm.db2.jcc.DB2Driver

jdbc:db2://<HOST>:<PORT>/
<DB.NAME>

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

35

Installing the BAM Server on Red Hat JBoss Application Server

3. Save and close the jdbc-config.xml file.

Modifying DFC session properties


Modify DFC session properties in dfc-config.xml to enable the BAM server to connect to the
Repository.
To modify DFC session properties:
1. Open dfc-config.xml available in one of the following paths:
Windows: [Temporary WAR location]\bam-server.war\WEB-INF\classes\config\
UNIX/Linux: [Temporary WAR location]/bam-server.war/WEB-INF/classes/config/
2. Modify the following Repository properties displayed in bold and italicized font:
<session repository="
$C(BAM, DOCBASE_NAME)
">
<username>
$C(BAM, DOCBASE_USER)
</username>
<password encrypted="false">
$C(BAM, SECURE.DOCBASE_PASSWORD)
</password>
</session>

Note: SECURE.DOCBASE_PASSWORD is entered in clear text. The password is encrypted


after installation.
3. Save and close the dfc-config.xml file.

Modifying the location of log files


Modify the location of the log files by updating the log4j.properties file.
To modify the location of log files:
1. Open the log4j.properties file available in one of the following paths:
Windows: [Temporary WAR location]\bam-server.war\WEB-INF\classes
UNIX/Linux: [Temporary WAR location]/bam-server.war/WEB-INF/classes
2. Modify the location of the log files according to the log4j standards. If you leave the location of
the log files unchanged, the log files are directed to the home path of the application server.
3. Save and close the log4j.properties file.

36

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Installing the BAM Server on Red Hat JBoss Application Server

Deploying the BAM application on the JBoss


application server
You can now deploy the updated files comprising bam-server.war on the application server.
To deploy the BAM application on the JBoss application server:
1. Install the BAM server web application by copying the entire bam-server.war folder from the
temporary WAR file location to the application servers deploy directory:
Copy the bam-server.war folder in the [Temporary WAR location] to the [JBoss server
root]\[Domain]\deploy\ folder.
2. Start the JBoss application server.
3. Browse to the bam-server URL to verify whether the BAM server is up and running.
For example, browse to http://<BAM server IP/machine name>:<port>/bam-server/.
If the BAM server is running, the BAM server Welcome page is displayed.
Note: If you are installing the BAM server on the JBoss application server instance used by
the Content Server, the domain name is DctmServer_MethodServer. Alternatively, by default,
the JBoss domain name is default.

Recommended JBoss application server


parameters settings
Change the JBoss application server parameters as follows:
Initial Java heap size: 512 m
Maximum Java heap size: 1024m
Java threads stack size: 128k
Initial size for the permanent generation heap: 128m
Maximum size for the permanent generation heap: 256m
Initial size of new generation pool: 128 m
Maximum size of new generation pool: 384m
Use parallel GC:
Number of threads used by parallel GC: 20

Changing the JBoss application server


parameters
1. Access one of the following folders:
Windows: [JBoss server root]\bin\
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

37

Installing the BAM Server on Red Hat JBoss Application Server

UNIX/Linux: [JBoss server root]/bin/


2. Modify run.bat (Windows) or run.sh (on UNIX/Linux).
For example, use the following settings for Sun Java 5:
set JAVA_OPTS=-server -XX:+UseParallelGC -Xms1024m -Xmx1024m
-XX:NewSize=128m -XX:MaxNewSize=256m -XX:MaxPermSize=256m

Post-installation guidelines
Changing the default host and port from TaskSpace to
point to the BAM server URL
If the application server does not use port 8080 by default, then the BAM server port number must be
configured in the BAM Port field of the Administration tab of TaskSpace.
If the BAM server and TaskSpace are not installed on the same physical machine, change the BAM
Host URL from localhost to the IP address of the BAM server machine. This procedure is completed
in the Administration tab of TaskSpace.
For instructions, see the Configuring connection settings section of the Business Activity Monitor
Implementation Guide.

Installing preconfigured dashboard


You can now install the preconfigured dashboard, if necessary. For instructions, see Installing the
preconfigured dashboards, page 88.

38

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Chapter 5
Installing the BAM Server on Apache
Tomcat Application Server
This chapter discusses the following:

Overview of installing BAM on Apache Tomcat

Creating BAM database objects manually

Creating Repository objects manually

Preparing the BAM server WAR file for deployment

Enabling DFC connections to the Repository

Specifying BAM database connection parameters

Modifying DFC session properties

Modifying the location of log files

Deploying the BAM application on the Tomcat application server

Recommended Tomcat application server parameters settings

Changing the Tomcat application server parameters

Post-installation guidelines

Overview of installing BAM on Apache Tomcat


This chapter describes the process of installing the BAM server manually on a machine where the
Apache Tomcat application server is installed. This installation assumes that the Content Server and
BAM database are installed on one or more different machines. Installing the BAM server requires the
completion of the following tasks: proper creation of the repository and database objects, and updating
the BAM configuration files. Finally, this chapter includes post-installation guidelines.
You must have the access rights of an administrator to perform the BAM server installation.
Note: For information about the platforms and application servers on which the BAM server can be
installed, see the Business Activity Monitor Release Notes.

Creating BAM database objects manually


Use the BAM Data Loader utility to create the BAM database and Repository objects (tables, types,
shipping data) manually, before you install the BAM server. You can also use this utility to clean the
BAM Repository and database objects when there are Repository- or database-related errors. This
utility is installed as part of the BAM server installer for JBoss and also resides in bam-product.zip.
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

39

Installing the BAM Server on Apache Tomcat Application Server

To create BAM database objects:


1. Access one of the following folders:
Windows: [Temporary BAM setup folder]\BAM Data Loader\bin\
UNIX/Linux: [Temporary BAM setup folder]/BAM Data Loader/bin/
2. Execute the following batch/shell files and when prompted, provide the BAM database connection
parameters on the command line:
For Microsoft SQL-Server:
Windows: create-db-objects-mssql.cmd
UNIX/Linux: create-db-objects-mssql.sh
For DB2 database:
Windows: create-db-objects-db2.cmd
UNIX/Linux: create-db-objects-db2.sh
For Oracle database:
Windows: create-db-objects-oracle.cmd
UNIX/Linux: create-db-objects-oracle.sh

The database connection parameters you must specify are as follows:


JAVA_HOME: Enter the Java runtime home path (Java JRE must exist on your computer).
For example: C:\Program Files\Java\jre1.6.
database user: Enter the name of the BAM database owner.
database password: Enter the password of the BAM database owner.
database host: Enter the host name or IP address of the database server.
database port: Enter the port of the database server.
database name: For Oracle: Enter the SID. For DB2 and SQL-Server: Enter the database
name.
CAUTION: When executing the database creation script you must make sure that the path to
the JRE entered in the command line is valid. If an invalid path is provided the creation script
fails, however, no error is provided in the log file. If you have any doubts about the validity of the
JRE path, check the BAM database to make sure that the objects were created.
3. Verify the results of running the SQL script by viewing the following log file in one of the
specified paths:
Windows: [Temporary BAM setup folder]\BAM Data Loader\log\data-loader.log
UNIX/Linux: [Temporary BAM setup folder]/BAM Data Loader/log/data-loader.log

Creating Repository objects manually


The Repository creation scripts run locally on the Content Server machine. Before executing the
relevant script, copy the [Temporary BAM setup folder]\BAM Data Loader\ folder to the Content
Server machine.
40

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Installing the BAM Server on Apache Tomcat Application Server

To create the Repository objects:


1. Access one of the following folders:
Windows: [Temporary BAM setup folder]\BAM Data Loader\bin\
UNIX/Linux: [Temporary BAM setup folder]/BAM Data Loader/bin/
2. Run one of the following batch/shell files:
Windows: create-repo-objects.cmd
UNIX/Linux: create-repo-objects.sh
3. When prompted, provide the following Repository connection parameters on the command line:
repository name
login name (repository owner or administrator name)
password
When you run the create-repo-objects command, you get the following outputs:
run-api finished with errorlevel = 0
run-dql finished with errorlevel = 1
This output is normal.
4. Verify the results of running the SQL script by viewing the following log files in the BAM Data
Loader folder:
run-api.log
run-dql.log

Preparing the BAM server WAR file for


deployment
Perform the following procedure to prepare the BAM server WAR file for deployment.
To prepare the BAM server WAR file for deployment:
1. Create [Temporary WAR location and the bam-server folder under it.
2. Access one of the following folders:
Windows: [Temporary BAM setup folder]\BAM Server\
UNIX/Linux: [Temporary BAM setup folder]/BAM Server/
3. Unpack the bam-server.war file into the [Temporary WAR location]\bam-server folder.
Note: After unpacking the bam-server.war file, ensure that the [Temporary WAR
location]\bam-server contains the following folders: html, META-INF, repgen, and WEB-INF, and
the version.properties file.
For instructions about unpacking the WAR file, see Unpacking WAR Files, page 109.
4. If you are using an Oracle 10 or 11 BAM database, complete the steps below. Otherwise, proceed
to step 5.

a. Delete the ojdbc14.jar file located in bam-server.war\WEB-INF\lib.


EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

41

Installing the BAM Server on Apache Tomcat Application Server

b. From the bam-product-supplemental_files.zip file you downloaded from the EMC Download
Center, open bam-product-supplemental_files\Oracle.

c. If you are using JDK 1.5, copy the ojdbc5.jar file to bam-server.war\WEB-INF\lib.
d. If you are using JDK 1.6, copy the ojdbc6.jar file to bam-server.war\WEB-INF\lib.
5. Modify the dfc.properties file using instructions in Enabling DFC connections to the Repository,
page 34. Perform this procedure before attempting to connect to Documentum repositories.
6. Modify the jdbc-config.xml file using instructions in Specifying BAM database connection
parameters, page 35.
7. Modify the dfc-config.xml file using instructions in Modifying DFC session properties, page 36.
8. Modify the log4j.properties file using instructions in Modifying the location of log files, page 36.
Note: Externalizing BAM configuration files, page 115 is another approach used to configure the
BAM server.

Enabling DFC connections to the Repository


Connection broker values must be entered in dfc.properties before BAM is able to connect with a
Repository.
To enable DFC connections to the Repository:
1. Open the dfc.properties file available in one of the following paths where you unpacked the
WAR file:
Windows: [Temporary WAR location]\bam-server.war\WEB-INF\classes
UNIX/Linux: [Temporary WAR location]/bam-server.war/WEB-INF/classes
2. Perform one of the following tasks:

a. If you are installing the BAM server on the Content Server computer, replace
the first line of the dfc.properties file with the following statement:#include
[documentum_user_dir]\config\dfc.properties.

For example, specify the path to the dfc.properties file as follows: #include
C:\Documentum\config\dfc.properties.
b. If you are installing the BAM server on a computer other than the Content Server computer,
delete or comment the #include statement. Then, specify the required values for the following
parameters:
dfc.docbroker.host[0]=host_name
dfc.docbroker.port[0]=port_number
3. Save and close the dfc.properties file.

42

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Installing the BAM Server on Apache Tomcat Application Server

Specifying BAM database connection


parameters
BAM database connection parameters entered in jdbc-config.xml enable the BAM server to connect
to the BAM database.
To specify BAM database connection parameters:
1. Open the jdbc-config.xml file available in one of the following paths:
Windows: [Temporary WAR location\bam-server.war\WEB-INF\classes\config\
UNIX/Linux: [Temporary WAR location/bam-server.war/WEB-INF/classes/config/
2. Modify the following BAM database connection parameters with the relevant values by editing
the XML file. You can open the XML file using a standard file editor or an XML Editor. Modify
the following XML element values:
dialect For example, in the case of MS SQL, change <dialect>$C(BAM,
DCTM_BAM_DB_DIALECT)</dialect> to <dialect>mssql</dialect>
URL
driver
username
password
Use the RDBMS Type, Dialect, and Driver Class values specified in the following table, and
specify the Connection URL based on your RDBMS environment:
Table 6

BAM Database connection parameters and values

RDBMS
Type

Dialect

Driver Class

Connection URL

MS SQL

mssql

com.microsoft.com.microsoft.

jdbc:sqlserver://<HOST>:<PORT>;

sqlserver.jdbc.SQLServer
Driver

databasename=<DB.NAME>;
SELECTMETHOD=Cursor

Oracle

oracle

oracle.jdbc.driver.OracleDriver

jdbc:oracle:thin:@<HOST>:
<PORT>:<SID>

DB2

db2

com.ibm.db2.jcc.DB2Driver

jdbc:db2://<HOST>:<PORT>/
<DB.NAME>

3. Save and close the jdbc-config.xml file.

Modifying DFC session properties


Modify DFC session properties in dfc-config.xml to enable the BAM server to connect to the
Repository.
To modify DFC session properties:
1. Open dfc-config.xml available in one of the following paths:
Windows: [Temporary WAR location]\bam-server.war\WEB-INF\classes\config\
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

43

Installing the BAM Server on Apache Tomcat Application Server

UNIX/Linux: [Temporary WAR location]/bam-server.war/WEB-INF/classes/config/


2. Modify the following Repository properties displayed in bold and italicized font:
<session repository="
$C(BAM, DOCBASE_NAME)
">
<username>
$C(BAM, DOCBASE_USER)
</username>
<password encrypted="false">
$C(BAM, SECURE.DOCBASE_PASSWORD)
</password>
</session>

Note: SECURE.DOCBASE_PASSWORD is entered in clear text. The password is encrypted


after installation.
3. Save and close the dfc-config.xml file.

Modifying the location of log files


Modify the location of the log files by updating the log4j.properties file.
To modify the location of log files:
1. Open the log4j.properties file available in one of the following paths:
Windows: [Temporary WAR location]\bam-server.war\WEB-INF\classes
UNIX/Linux: [Temporary WAR location]/bam-server.war/WEB-INF/classes
2. Modify the location of the log files according to the log4j standards. If you leave the location of
the log files unchanged, the log files are directed to the home path of the application server.
3. Save and close the log4j.properties file.

Deploying the BAM application on the Tomcat


application server
You can now deploy the updated files comprising the bam-server folder on the Tomcat application
server.
To deploy the BAM application on Tomcat application server:
1. Install the BAM server by copying the entire bam-server folder from the temporary WAR file
location to the webapps directory of the application server.

Copy the bam server folder in [Temporary WAR location] to the [Tomcat server
root]\webapps\ folder.
2. Start the Tomcat application server.
3. Browse to the bam-server URL to verify whether the BAM server is up and running.
44

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Installing the BAM Server on Apache Tomcat Application Server

For example, browse to http://<BAM server IP/machine name>:<port>/bam-server/.


If the BAM server is up and running, the following console message is displayed:
INFO: Server startup in XXXX ms

Recommended Tomcat application server


parameters settings
Change the Tomcat application server parameters as follows:
Initial Java heap size: 512 m
Maximum Java heap size: 1024m
Java threads stack size: 128k
Initial size for the permanent generation heap: 128m
Maximum size for the permanent generation heap: 256m
Initial size of new generation pool: 128 m
Maximum size of new generation pool: 384m
Use parallel GC:
Number of threads used by parallel GC: 20

Changing the Tomcat application server


parameters
To change the Tomcat application server parameters:
1. Access one of the following folders:
Windows: [Tomcat server root]\bin\
UNIX/Linux: [Tomcat server root]/bin/
2. Modify catalina.bat (Windows) or catalina.sh (on UNIX/Linux).

For example, use the following settings for Tomcat:


set JAVA_OPTS=-server -XX:+UseParallelGC -Xms1024m -Xmx1024m
-XX:NewSize=128m -XX:MaxNewSize=256m -XX:MaxPermSize=256m

Post-installation guidelines
Changing the default host and port from TaskSpace to
point to the BAM server URL
If the application server does not use port 8080 by default, then the BAM server port number must be
configured in the BAM Port field of the Administration tab of TaskSpace.
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

45

Installing the BAM Server on Apache Tomcat Application Server

If the BAM server and TaskSpace are not installed on the same physical machine, change the BAM
Host URL from localhost to the IP address of the BAM server machine. This procedure is completed
in the Administration tab of TaskSpace.
For instructions, see the Configuring connection settings section of the Business Activity Monitor
Implementation Guide.

Installing preconfigured dashboard


You can now install the preconfigured dashboard, if necessary. For instructions, see Installing the
preconfigured dashboards, page 88.

46

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Chapter 6
Installing the BAM Server on Oracle
Weblogic Application Server
This chapter discusses the following:

Overview of installing BAM on Oracle WebLogic

Creating BAM database objects manually

Creating Repository objects manually

Preparing the BAM server WAR file for deployment

Enabling DFC connections to the Repository

Specifying BAM database connection parameters

Modifying DFC session properties

Modifying the location of log files

Creating an external configuration folder

Deploying the BAM application on the WebLogic application server

Recommended WebLogic application server parameters settings

Post-installation guidelines

Overview of installing BAM on Oracle WebLogic


This chapter describes the process of installing the BAM server manually on a machine where Oracle
WebLogic Server is installed. This installation assumes that the Content Server and BAM database are
installed on different machines. Installing the BAM server requires the completion of the following
tasks: creation of the repository and database objects, and updating the BAM configuration files.
Finally, this chapter includes post-installation guidelines.
You must have the access rights of an administrator to perform the BAM server installation.
Note: For information about the platforms and application servers on which the BAM server can be
installed, see the Business Activity Monitor Release Notes.

Creating BAM database objects manually


Use the BAM Data Loader utility to create the BAM database and Repository objects (tables, types,
shipping data) manually, before you install the BAM server. You can also use this utility to clean the
BAM Repository and database objects when there are Repository- or database-related errors. This
utility is installed as part of the BAM server installer for JBoss and also resides in bam-product.zip.
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

47

Installing the BAM Server on Oracle Weblogic Application Server

To create BAM database objects:


1. Access one of the following folders:
Windows: [Temporary BAM setup folder]\BAM Data Loader\bin\
UNIX/Linux: [Temporary BAM setup folder]/BAM Data Loader/bin/
2. Execute the following batch/shell files and when prompted, provide the BAM database connection
parameters on the command line:
For Microsoft SQL-Server:
Windows: create-db-objects-mssql.cmd
UNIX/Linux: create-db-objects-mssql.sh
For DB2 database:
Windows: create-db-objects-db2.cmd
UNIX/Linux: create-db-objects-db2.sh
For Oracle database:
Windows: create-db-objects-oracle.cmd
UNIX/Linux: create-db-objects-oracle.sh

The database connection parameters you must specify are as follows:


JAVA_HOME: Enter the Java runtime home path (Java JRE must exist on your computer).
For example: C:\Program Files\Java\jre1.6.
database user: Enter the name of the BAM database owner.
database password: Enter the password of the BAM database owner.
database host: Enter the host name or IP address of the database server.
database port: Enter the port of the database server.
database name: For Oracle: Enter the SID. For DB2 and SQL-Server: Enter the database
name.
CAUTION: When executing the database creation script you must make sure that the path to
the JRE entered in the command line is valid. If an invalid path is provided the creation script
fails, however, no error is provided in the log file. If you have any doubts about the validity of the
JRE path, check the BAM database to make sure that the objects were created.
3. Verify the results of running the SQL script by viewing the following log file in one of the
specified paths:
Windows: [Temporary BAM setup folder]\BAM Data Loader\log\data-loader.log
UNIX/Linux: [Temporary BAM setup folder]/BAM Data Loader/log/data-loader.log

Creating Repository objects manually


The Repository creation scripts run locally on the Content Server machine. Before executing the
relevant script, copy the [Temporary BAM setup folder]\BAM Data Loader\ folder to the Content
Server machine.
48

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Installing the BAM Server on Oracle Weblogic Application Server

To create the Repository objects:


1. Access one of the following folders:
Windows: [Temporary BAM setup folder]\BAM Data Loader\bin\
UNIX/Linux: [Temporary BAM setup folder]/BAM Data Loader/bin/
2. Run one of the following batch/shell files:
Windows: create-repo-objects.cmd
UNIX/Linux: create-repo-objects.sh
3. When prompted, provide the following Repository connection parameters on the command line:
repository name
login name (repository owner or administrator name)
password
When you run the create-repo-objects command, you get the following outputs:
run-api finished with errorlevel = 0
run-dql finished with errorlevel = 1
This output is normal.
4. Verify the results of running the SQL script by viewing the following log files in the BAM Data
Loader folder:
run-api.log
run-dql.log

Preparing the BAM server WAR file for


deployment
1. Create a [Temporary WAR location] folder and within it, create a bam-server.war folder.
2. Access one of the following folders:
Windows: [Temporary BAM setup folder]\BAM Server\
UNIX/Linux: [Temporary BAM setup folder]/BAM Server/
3. Unpack the bam-server.war file into the [Temporary WAR location]\bam-server.war folder. For
instructions about unpacking the WAR file, see Unpacking WAR Files, page 109.
4. If you are using an Oracle 10 or 11 BAM database, complete the steps below. Otherwise, proceed
to step 5.

a. Delete the ojdbc14.jar file located in bam-server.war\WEB-INF\lib.


b. From the bam-product-supplemental_files.zip file you downloaded from the EMC Download
Center, open bam-product-supplemental_files\Oracle.

c. If you are using JDK 1.5, copy the ojdbc5.jar file to bam-server.war\WEB-INF\lib.
d. If you are using JDK 1.6, copy the ojdbc6.jar file to bam-server.war\WEB-INF\lib.
5. Modify the dfc.properties file using instructions in Enabling DFC connections to the Repository,
page 50. Perform this procedure before attempting to connect to Documentum repositories.
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

49

Installing the BAM Server on Oracle Weblogic Application Server

6. Modify the jdbc-config.xml file using instructions in Specifying BAM database connection
parameters, page 50.
7. Modify the dfc-config.xml file using instructions in Modifying DFC session properties, page 51.
8. Modify the log4j.properties file using instructions in Modifying the location of log files, page 52.
Note: Externalizing BAM configuration files, page 115 is another approach used to configure the
BAM server.

Enabling DFC connections to the Repository


Connection broker values must be entered in dfc.properties before BAM is able to connect with a
Repository.
To enable DFC connections to the Repository:
1. Open the dfc.properties file available in the following path where you unpacked the WAR file:
Windows: [Temporary WAR location]\bam-server.war\WEB-INF\classes
UNIX/Linux: [Temporary WAR location]/bam-server.war/WEB-INF/classes
2. Perform one of the following tasks:

a. If you are installing the BAM server on the Content Server computer, replace
the first line of the dfc.properties file with the following statement:#include
[documentum_user_dir]\config\dfc.properties.

For example, specify the path to the dfc.properties file as follows: #include
C:\Documentum\config\dfc.properties

b. If you are installing the BAM server on a computer other than the Content Server computer,
delete, or comment the #include statement. Then, specify the required values for the following
parameters:
dfc.docbroker.host[0]=host_name
dfc.docbroker.port[0]=port_number
3. Save and close the dfc.properties file.

Specifying BAM database connection


parameters
BAM database connection parameters entered in jdbc-config.xml enable the BAM server to connect
to the BAM database.
To specify BAM database connection parameters:
1. Open the jdbc-config.xml file available in one of the following paths where you unpacked the
WAR file:
Windows: [Temporary WAR location]\bam-server.war\WEB-INF\classes
UNIX/Linux: [Temporary WAR location]/bam-server.war/WEB-INF/classes
50

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Installing the BAM Server on Oracle Weblogic Application Server

2. Modify the following BAM database connection parameters with the relevant values by editing
the XML file. You can open the XML file using a standard file editor or an XML editor. Modify
the following XML element values:
dialect: For example, in the case of MS SQL, change <dialect>$C(BAM,
DCTM_BAM_DB_DIALECT)</dialect> to <dialect>mssql</dialect>
URL
driver
username
password
Use the RDBMS Type, Dialect, and Driver Class values specified in the following table, and
specify the Connection URL based on your RDBMS environment:
Table 7

BAM Database connection parameters and values

RDBMS
Type

Dialect

Driver Class

Connection URL

MS SQL

mssql

com.microsoft.com.microsoft.

jdbc:sqlserver://<HOST>:<PORT>;

sqlserver.jdbc.SQLServer
Driver

databasename=<DB.NAME>;
SELECTMETHOD=Cursor

Oracle

oracle

oracle.jdbc.driver.OracleDriver

jdbc:oracle:thin:@<HOST>:
<PORT>:<SID>

DB2

db2

com.ibm.db2.jcc.DB2Driver

jdbc:db2://<HOST>:<PORT>/
<DB.NAME>

3. Save and close the jdbc-config.xml file.

Modifying DFC session properties


Modify DFC session properties in dfc-config.xml to enable the BAM server to connect to the
Repository.
Note: Use administrator credentials to connect from the BAM server to the Repository.
To modify DFC session properties:
1. Open the dfc-config.xml file available in one of the following paths where you unpacked the
WAR file:
Windows: [Temporary WAR location]\bam-server.war\WEB-INF\classes\config\
UNIX/Linux: [Temporary WAR location]/bam-server.war/WEB-INF/classes/config/
2. Modify the following repository properties displayed in bold and italicized font:
<session repository="
$C(BAM, DOCBASE_NAME)
">
<username>
$C(BAM, DOCBASE_USER)
</username>
<password encrypted="false">

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

51

Installing the BAM Server on Oracle Weblogic Application Server

$C(BAM, SECURE.DOCBASE_PASSWORD)
</password>
</session>

Note: SECURE.DOCBASE_PASSWORD is entered in clear text. The password is encrypted


after installation.
3. Save and close the dfc-config.xml file.

Modifying the location of log files


1. Open the log4j.properties file available in one of the following paths where you unpacked the
WAR file:
Windows: [Temporary WAR location]\bam-server.war\WEB-INF\classes\
UNIX/Linux: [Temporary WAR location]/bam-server.war/WEB-INF/classes/
2. Modify the location of the log files according to the log4j standards. If you leave the location of
the log files unchanged, the log files are directed to the home path of the application server.
3. Save and close the log4j.properties file.

Creating an external configuration folder


Create an external configuration folder before deploying BAM. The external configuration folder is
referred to by the BAM application.
To create an external configuration folder:
1. Create a WebLogic Server domain, or use an existing domain.
2. Create an external configuration folder, [bpm.resource.dir]. For example, create the configuration
folder in the following path: C:\Documentum\bam\configuration. This folder stores the BAM
configuration files in the WebLogic environment.
3. Unpack the contents of the [Temporary WAR location]\bam-server.war\WEB-INF\classes\config\
folder into the [bpm.resource.dir] folder.
4. Modify the startup script by adding the following line at the beginning of startWebLogic.cmd (on
Windows) or startWebLogic.sh (on UNIX/Linux):
Windows: set JAVA_OPTIONS=%JAVA_OPTIONS%
-Dbpm.resource.dir=[bpm.resource.dir]

UNIX/Linux: JAVA_OPTIONS=${JAVA_OPTIONS}
-Dbpm.resource.dir=[bpm.resource.dir]

In this step, you define a new Java property, bpm.resource.dir, with the value of the
external configuration folder location that the BAM application references. For example,
Dbpm.resource.dir=c:\Documentum\configuration\bam.
Note: Ensure that the variable contains the absolute path of the location of the BAM configuration
files.
52

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Installing the BAM Server on Oracle Weblogic Application Server

5. Start the WebLogic Server domain.


6. Open the WebLogic Server Administration Console.

Deploying the BAM application on the


WebLogic application server
This section provides additional instructions to complete the deployment of the BAM server. Use the
WebLogic Server Administration Console to deploy BAM. Make sure to deploy the bam-server.war
in which you modified the configuration files.
To deploy the BAM application on Weblogic application server:
1. Start the WebLogic application server.
2. Open the WebLogic Server Administration Console by specifying the WebLogic Server
Administration URL. The URL must be defined in this format: http://<host:port>/console.
3. Specify the login credentials and click Login.
4. In the Domain Structure pane, select Deployments.
The Summary of Deployments is displayed in the Control tab of the Right pane.
5. In the Change Center pane, click Lock & Edit to disallow others from editing the domain.
6. Click Install in the Summary of Deployments page to install the BAM server.
7. In the next page, select bam-server.war.
8. Click Next.
9. Select the Install this deployment as an application option, and click Next.
10. Verify that the name of the deployment is bam-server and click Next.
11. In the next page, select No, I will review the configuration later option.
12. Click Finish. After the deployment is successfully installed, activate the pending changes to
commit the deployment and other updates to the active system.
13. Click Activate Changes in the Change Center pane.
A message is displayed indicating that all changes have been activated.
14. In the Control tab of the Summary of Deployments page, select the bam-server deployment.
15. In the Start drop-down list, select Servicing all requests.
The Start Application Assistant page is displayed.
16. Click Yes to confirm.
The BAM application is started.
17. Ensure that the State of the bam-server deployment is Active.
18. Browse to the bam-server URL to verify whether the BAM server is up and running.
For example, browse to http://<BAM server IP/machine name>:<port>/bam-server/.
If the BAM server is running, the BAM server Welcome page is displayed.
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

53

Installing the BAM Server on Oracle Weblogic Application Server

Recommended WebLogic application server


parameters settings
Change the WebLogic application server parameters as follows:
Maximum Java heap size: 1024m
Use parallel GC:
Number of threads used by parallel GC: 20

Post-installation guidelines
Changing the default host and port from TaskSpace to
point to the BAM server URL
If the application server does not use port 8080 by default, then the BAM server port number must be
configured in the BAM Port field of the Administration tab of TaskSpace.
If the BAM server and TaskSpace are not installed on the same physical machine, change the BAM
Host URL from localhost to the IP address of the BAM server machine. This procedure is completed
in the Administration tab of TaskSpace.
For instructions, see the Configuring connection settings section of the Business Activity Monitor
Implementation Guide.

Installing preconfigured dashboard


You can now install the preconfigured dashboard, if necessary. For instructions, see Installing the
preconfigured dashboards, page 88.

54

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Chapter 7
Installing the BAM Server on IBM
WebSphere Application Server
This chapter discusses the following:

Overview of installing BAM on WebSphere

Creating BAM database objects manually

Creating Repository objects manually

Preparing the BAM server WAR file for deployment

Enabling DFC connections to the Repository

Specifying BAM database connection parameters

Modifying DFC session properties

Modifying the location of log files

Configuring the WebSphere application server

Deploying the BAM application on the WebSphere application server

Generating a new Java keystore file

Recommended IBM WebSphere application server parameters settings

Post-installation guidelines

Overview of installing BAM on WebSphere


This chapter describes the process of installing the BAM server manually on a machine where the
IBM WebSphere application server is installed. This installation assumes that the Content Server and
BAM database are installed on one or more different machines. Installing the BAM server requires the
completion of the following tasks: proper creation of the repository and database objects, and updating
the BAM configuration files. Finally, this chapter includes post-installation guidelines.
Note: You must have the access rights of an administrator to perform the BAM server installation.
Note: For information about the platforms and application servers on which the BAM server can be
installed, see the Business Activity Monitor Release Notes.

Creating BAM database objects manually


Use the BAM Data Loader utility to create the BAM database and Repository objects (tables, types,
shipping data) manually, before you install the BAM server. You can also use this utility to clean the
BAM Repository and database objects when there are Repository- or database-related errors. This
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

55

Installing the BAM Server on IBM WebSphere Application Server

utility is installed as part of the BAM server installer for JBoss and also resides in bam-product.zip.
To create BAM database objects:
1. Access one of the following folders:
Windows: [Temporary BAM setup folder]\BAM Data Loader\bin\
UNIX/Linux: [Temporary BAM setup folder]/BAM Data Loader/bin/
2. Execute the following batch/shell files and when prompted, provide the BAM database connection
parameters on the command line:
For Microsoft SQL-Server:
Windows: create-db-objects-mssql.cmd
UNIX/Linux: create-db-objects-mssql.sh
For DB2 database:
Windows: create-db-objects-db2.cmd
UNIX/Linux: create-db-objects-db2.sh
For Oracle database:
Windows: create-db-objects-oracle.cmd
UNIX/Linux: create-db-objects-oracle.sh

The database connection parameters you must specify are as follows:


JAVA_HOME: Enter the Java runtime home path (Java JRE must exist on your computer).
For example: C:\Program Files\Java\jre1.6.
database user: Enter the name of the BAM database owner.
database password: Enter the password of the BAM database owner.
database host: Enter the host name or IP address of the database server.
database port: Enter the port of the database server.
database name: For Oracle: Enter the SID. For DB2 and SQL-Server: Enter the database
name.
CAUTION: When executing the database creation script you must make sure that the path to
the JRE entered in the command line is valid. If an invalid path is provided the creation script
fails, however, no error is provided in the log file. If you have any doubts about the validity of the
JRE path, check the BAM database to make sure that the objects were created.
3. Verify the results of running the SQL script by viewing the following log file in one of the
specified paths:
Windows: [Temporary BAM setup folder]\BAM Data Loader\log\data-loader.log
UNIX/Linux: [Temporary BAM setup folder]/BAM Data Loader/log/data-loader.log

Creating Repository objects manually


The Repository creation scripts run locally on the Content Server machine. Before executing the
relevant script, copy the [Temporary BAM setup folder]\BAM Data Loader\ folder to the Content
Server machine.
56

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Installing the BAM Server on IBM WebSphere Application Server

To create the Repository objects:


1. Access one of the following folders:
Windows: [Temporary BAM setup folder]\BAM Data Loader\bin\
UNIX/Linux: [Temporary BAM setup folder]/BAM Data Loader/bin/
2. Run one of the following batch/shell files:
Windows: create-repo-objects.cmd
UNIX/Linux: create-repo-objects.sh
3. When prompted, provide the following Repository connection parameters on the command line:
repository name
login name (repository owner or administrator name)
password
When you run the create-repo-objects command, you get the following outputs:
run-api finished with errorlevel = 0
run-dql finished with errorlevel = 1
This output is normal.
4. Verify the results of running the SQL script by viewing the following log files in the BAM Data
Loader folder:
run-api.log
run-dql.log

Preparing the BAM server WAR file for


deployment
This section provides instructions to prepare the BAM server WAR file for deployment. Preparing
the BAM server WAR file for deployment involves unpacking the bam-server.war file, updating the
relevant configuration files, and repacking the bam-server.war file. These tasks are completed before
the BAM server is deployed on IBM WebSphere application server. When the BAM server is deployed
into WebSphere, unpack and then repack the .WAR file that is provided on the EMC Download Center.
Use the following java Jar utility to execute this task: jar cvf bam-server.jar *.
Note: The jar utility is available in the following directory: <JDK>/bin.
The following command creates the bam-server.war file with content from the
C:\_tmp\AIX\bam-server.war folder. Please note that the period at the end of the command is part of
the jar command syntax: jar -cvf bam-server.war -C C:\_tmp\AIX\bam-server.war .
To prepare the BAM server WAR file for deployment:
1. Create [Temporary WAR location] and the bam-server.war folder under it.
2. Access one of the following folders:
Windows: [Temporary BAM setup folder]\BAM Server\
UNIX/Linux: [Temporary BAM setup folder]/BAM Server/
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

57

Installing the BAM Server on IBM WebSphere Application Server

3. Unpack the bam-server.war file into the [Temporary WAR location]\bam-server.war folder.
For instructions about unpacking the WAR file, see Unpacking WAR Files, page 109.
4. If you are using an Oracle 10 or 11 BAM database, complete the steps below. Otherwise, proceed
to step 5.

a. Delete the ojdbc14.jar file located in bam-server.war\WEB-INF\lib.


b. From the bam-product-supplemental_files.zip file you downloaded from the EMC Download
Center, open bam-product-supplemental_files\Oracle.

c. If you are using JDK 1.5, copy the ojdbc5.jar file to bam-server.war\WEB-INF\lib.
d. If you are using JDK 1.6, copy the ojdbc6.jar file to bam-server.war\WEB-INF\lib.
5. Modify the dfc.properties file using instructions in Enabling DFC connections to the Repository,
page 42. Perform this procedure before attempting to connect to Documentum repositories.
6. Modify the jdbc-config.xml file using instructions in Specifying BAM database connection
parameters, page 43.
7. Modify the dfc-config.xml file using instructions in Modifying DFC session properties, page 43.
8. Modify the log4j.properties file using instructions in Modifying the location of log files, page 44.
9. If you are deploying BAM on WebSphere version 7.0.0.7, replace jaxen-full.jar
in bam-server.war\WEB-INF\lib with the jaxen-full.jar file located in
bam-product-supplemental_files.zip\WebSphere\7.0.0.7\Required jars\jaxen-full.jar.
10. Create a deployment archive bam-server.war that includes all the updated configuration file
changes.
Repack the bam-server.war file comprising the updated configuration files, and then deploy the
bam-server.war file on the IBM WebSphere application. For instructions about repacking the
WAR file, see Repacking WAR Files, page 109.
Note: Externalizing BAM configuration files, page 115 is another approach used to configure the
BAM server.

Enabling DFC connections to the Repository


Connection broker values must be entered in dfc.properties before BAM is able to connect with a
Repository.
To enable DFC connections to the Repository:
1. Open the dfc.properties file available in one of the following paths where you unpacked the
WAR file:
Windows: [Temporary WAR location]\bam-server.war\WEB-INF\classes
UNIX/Linux: [Temporary WAR location]/bam-server.war/WEB-INF/classes
2. Perform one of the following tasks:

a. If you are installing the BAM server on the Content Server computer, replace
the first line of the dfc.properties file with the following statement:#include
[documentum_user_dir]\config\dfc.properties.

For example, specify the path to the dfc.properties file as follows: #include
C:\Documentum\config\dfc.properties.
58

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Installing the BAM Server on IBM WebSphere Application Server

b. If you are installing the BAM server on a computer other than the Content Server computer,
delete or comment the #include statement. Then, specify the required values for the following
parameters:
dfc.docbroker.host[0]=host_name
dfc.docbroker.port[0]=port_number
3. Save and close the dfc.properties file.

Specifying BAM database connection


parameters
BAM database connection parameters entered in jdbc-config.xml enable the BAM server to connect
to the BAM database.
To specify BAM database connection parameters:
1. Open the jdbc-config.xml file available in one of the following paths:
Windows: [Temporary WAR location\bam-server.war\WEB-INF\classes\config\
UNIX/Linux: [Temporary WAR location/bam-server.war/WEB-INF/classes/config/
2. Modify the following BAM database connection parameters with the relevant values by editing
the XML file. You can open the XML file using a standard file editor or an XML Editor. Modify
the following XML element values:
dialect For example, in the case of MS SQL, change <dialect>$C(BAM,
DCTM_BAM_DB_DIALECT)</dialect> to <dialect>mssql</dialect>
URL
driver
username
password
Use the RDBMS Type, Dialect, and Driver Class values specified in the following table, and
specify the Connection URL based on your RDBMS environment:
Table 8

BAM Database connection parameters and values

RDBMS
Type

Dialect

Driver Class

Connection URL

MS SQL

mssql

com.microsoft.com.microsoft.

jdbc:sqlserver://<HOST>:<PORT>;

sqlserver.jdbc.SQLServer
Driver

databasename=<DB.NAME>;
SELECTMETHOD=Cursor

Oracle

oracle

oracle.jdbc.driver.OracleDriver

jdbc:oracle:thin:@<HOST>:
<PORT>:<SID>

DB2

db2

com.ibm.db2.jcc.DB2Driver

jdbc:db2://<HOST>:<PORT>/
<DB.NAME>

3. Save and close the jdbc-config.xml file.


EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

59

Installing the BAM Server on IBM WebSphere Application Server

Modifying DFC session properties


Modify DFC session properties in dfc-config.xml to enable the BAM server to connect to the
Repository.
To modify DFC session properties:
1. Open dfc-config.xml available in one of the following paths:
Windows: [Temporary WAR location]\bam-server.war\WEB-INF\classes\config\
UNIX/Linux: [Temporary WAR location]/bam-server.war/WEB-INF/classes/config/
2. Modify the following Repository properties displayed in bold and italicized font:
<session repository="
$C(BAM, DOCBASE_NAME)
">
<username>
$C(BAM, DOCBASE_USER)
</username>
<password encrypted="false">
$C(BAM, SECURE.DOCBASE_PASSWORD)
</password>
</session>

Note: SECURE.DOCBASE_PASSWORD is entered in clear text. The password is encrypted


after installation.
3. Save and close the dfc-config.xml file.

Modifying the location of log files


Modify the location of the log files by updating the log4j.properties file.
To modify the location of log files:
1. Open the log4j.properties file available in one of the following paths:
Windows: [Temporary WAR location]\bam-server.war\WEB-INF\classes
UNIX/Linux: [Temporary WAR location]/bam-server.war/WEB-INF/classes
2. Modify the location of the log files according to the log4j standards. If you leave the location of
the log files unchanged, the log files are directed to the home path of the application server.
3. Save and close the log4j.properties file.

Configuring the WebSphere application server


The WebSphere application server must be configured before it is deployed. Configuration involves
copying and replacing files in your WebSphere directory. Deploying a BAM application involves
using the WebSphere Application Server Administration Console.
60

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Installing the BAM Server on IBM WebSphere Application Server

Note: If you are deploying BAM on WebSphere version 7.0.0.x, the jaxen-full.jar file
in bam-server.war/WEB-INF/lib must be replaced with the jaxen-full.jar file located in
bam-product-supplemental_files.zip/WebSphere/7.0.0.7/Required jars/jaxen-full.jar. This file
replacement is done prior to repacking the bam-server.war file.
Follow the instructions in this section to configure the WebSphere application server before you deploy
the BAM application on it.
To configure the WebSphere application server:
1. Change directory to [WebSphere root]/optionalLibraries.
2. Create a folder with the name BAM.
3. Copy the following jar files to BAM directory you just created:
[Temporary WAR location]\bamserver.war\WEB-INF\lib\aspectjrt.jar
[Temporary WAR location]\bamserver.war\WEB-INF\lib\saaj-api.jar
[Temporary WAR location]\bamserver.war\WEB-INF\lib\saaj-impl.jar
[Temporary BAM setup folder]\BAM Server\WebSphere\Required JARs\xalan.jar
[Temporary BAM setup folder]\BAM Server\WebSphere\Required JARs\xercesImpl.jar.
4. In WebSphere Administration Console select Environment > Shared Libraries.
5. In the Scope list box select Cell=Cell_Name.
6. Create a shared library for each jar that was copied:

a. Select New.
b. Enter a name for the library.
c. In the Classpath field enter
${WAS_INSTALL_ROOT}/optionalLibraries/BAM/[jar_name].

d. Select Apply and Save.

Deploying the BAM application on the


WebSphere application server
You can now deploy the BAM application on the WebSphere application server.
To deploy the BAM application on the WebSphere application server:
1. Open the WebSphere Application Server Administration Console.
The format of the URL is as follows: http://<host>:<port>/ibm/console.
The Welcome page is displayed.
2. In the Left pane, expand the Applications node, and click Install New Application.
3. Select the Local file system option and specify the Full path of the bam-server.war file.
4. In the Context root box, specify bam-server.
5. Click Next.
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

61

Installing the BAM Server on IBM WebSphere Application Server

The Select installation options page is displayed.


6. Select the Precompile JavaServer Pages files option.
7. Select the Deploy Web services option.
8. Click Next.
The Map modules to servers page is displayed.
9. Click Next.
The Map virtual hosts for Web modules page is displayed.
10. Click Next.
The Summary page is displayed.
11. Click Finish.
The BAM server is deployed on the WebSphere application server. On the page that is displayed,
click Save to save changes that you made to the local configuration, to the master configuration.
12. Configure the class loading strategy for the BAM server by performing the following steps:

a. In the Left pane, expand the Applications node, and click Enterprise Applications.
The Enterprise Applications page is displayed.
b. Select the bam-server.war application.
c. Click the bam-server.war link.
d. In the next page that is displayed, click the Class loading and update detection link.
e. In the General Properties page that is displayed, specify 120 seconds in the Polling interval
for updated files box.

f. Select the Class loaded with application class loader first option as the Class loader order.
g. Click OK.
The next page displays a message indicating that the changes have been made to your
local configuration.
h. Click Save to save the local configuration changes made to the master configuration.
i. On the Enterprise Applications page select the bam-server.war application.
j. Select Shared library references.
k. Select the bam-server.war application and click Reference shared library.
l. Transfer all libraries created during step 6 of the Configuring the WebSphere Application Server
section from the Available list to the Selected list.

m. Select OK.
n. Select OK and Save.
o. In the Enterprise Applications page, select the bam-server.war application and click Start.
13. Restart the WebSphere application server.
14. Browse to the bam-server URL to verify whether the BAM server is up and running.
For example, browse to http://<BAM server IP/machine name>:<port>/bam-server/.
If the BAM server is running, the BAM server Welcome page is displayed.
62

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Installing the BAM Server on IBM WebSphere Application Server

Generating a new Java keystore file


When BAM is deployed on Websphere 6.1.0.17 that uses the JDK from IBM, BAM fails to connect to
the repository. If you have already deployed the BAM server on Websphere, prepare a new deployment
according the procedure and then redeploy. A new deployment is necessary because the java keystore
file that is dynamically created during deployment is corrupted. The work-around to this issue involves
using the BAM Data Loader to create a replacement java keystore. The BAM Data Loader consists
of a batch file called test-repository.cmd located in the bin folder. For Unix, the batch file is called
test-repository.sh. The primary purpose of this file is to generate a dfc.keystore file that is required
when deploying the BAM server on Websphere.
To generate a new Java keystore file:
1. Open the <BAM Data Loader>/bin folder.
2. Configure the repository parameters in the dfc.properties file.
3. Run either test-repository.cmd or test-repository.sh. The dfc.keystore file is created in <BAM
Data Loader>/bin.
4. Copy the dfc.keystore file to the bam-server.war/WEB-INF/classes/ folder before deploying
BAM. If the bam-server.war file is compressed, then it must be repackaged.
5. Deploy bam-server.war on Websphere according to the BAM Installation Guide.

Recommended IBM WebSphere application


server parameters settings
Change the IBM WebSphere application server parameters as follows:
Initial Java heap size: 512 m
Maximum Java heap size: 1024m
Use parallel GC:
Number of threads used by parallel GC: 20

Post-installation guidelines
Changing the default host and port from TaskSpace to
point to the BAM server URL
If the application server does not use port 8080 by default, then the BAM server port number must be
configured in the BAM Port field of the Administration tab of TaskSpace.
If the BAM server and TaskSpace are not installed on the same physical machine, change the BAM
Host URL from localhost to the IP address of the BAM server machine. This procedure is completed
in the Administration tab of TaskSpace.
For instructions, see the Configuring connection settings section of the Business Activity Monitor
Implementation Guide.
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

63

Installing the BAM Server on IBM WebSphere Application Server

Installing preconfigured dashboard


You can now install the preconfigured dashboard, if necessary. For instructions, see Installing the
preconfigured dashboards, page 88.

64

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Chapter 8
Installing the BAM Server on Oracle
Application Server
This chapter discusses the following:

Overview of installing BAM on Oracle application servers

Creating BAM database objects manually

Creating Repository objects manually

Preparing the BAM server WAR file for deployment

Enabling DFC connections to the Repository

Specifying BAM database connection parameters

Modifying DFC session properties

Modifying the location of log files

Deploying the BAM application on the Oracle application server

Recommended Oracle 10g application server parameters settings

Post-installation guidelines

Overview of installing BAM on Oracle


application servers
This chapter describes the process of installing the BAM server manually on a machine where only
the Oracle AS 10g R3 (10.1.3.3.0) application server is installed. This installation assumes that
the Content Server and BAM database are installed on another machine or on different machines.
Installing the BAM server requires the completion of the following tasks: proper creation of the
repository and database objects, and updating the BAM configuration files. Finally, this chapter
includes post-installation guidelines.
You must have the access rights of an administrator to perform the BAM server installation. In addition
use administrator credentials to connect from the BAM server to the repository.
Note: For information about the platforms and application servers on which the BAM server can be
installed, see the Business Activity Monitor Release Notes.

Creating BAM database objects manually


Use the BAM Data Loader utility to create the BAM database and Repository objects (tables, types,
shipping data) manually, before you install the BAM server. You can also use this utility to clean the
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

65

Installing the BAM Server on Oracle Application Server

BAM Repository and database objects when there are Repository- or database-related errors. This
utility is installed as part of the BAM server installer for JBoss and also resides in bam-product.zip.
To create BAM database objects:
1. Access one of the following folders:
Windows: [Temporary BAM setup folder]\BAM Data Loader\bin\
UNIX/Linux: [Temporary BAM setup folder]/BAM Data Loader/bin/
2. Execute the following batch/shell files and when prompted, provide the BAM database connection
parameters on the command line:
For Microsoft SQL-Server:
Windows: create-db-objects-mssql.cmd
UNIX/Linux: create-db-objects-mssql.sh
For DB2 database:
Windows: create-db-objects-db2.cmd
UNIX/Linux: create-db-objects-db2.sh
For Oracle database:
Windows: create-db-objects-oracle.cmd
UNIX/Linux: create-db-objects-oracle.sh

The database connection parameters you must specify are as follows:


JAVA_HOME: Enter the Java runtime home path (Java JRE must exist on your computer).
For example: C:\Program Files\Java\jre1.6.
database user: Enter the name of the BAM database owner.
database password: Enter the password of the BAM database owner.
database host: Enter the host name or IP address of the database server.
database port: Enter the port of the database server.
database name: For Oracle: Enter the SID. For DB2 and SQL-Server: Enter the database
name.
CAUTION: When executing the database creation script you must make sure that the path to
the JRE entered in the command line is valid. If an invalid path is provided the creation script
fails, however, no error is provided in the log file. If you have any doubts about the validity of the
JRE path, check the BAM database to make sure that the objects were created.
3. Verify the results of running the SQL script by viewing the following log file in one of the
specified paths:
Windows: [Temporary BAM setup folder]\BAM Data Loader\log\data-loader.log
UNIX/Linux: [Temporary BAM setup folder]/BAM Data Loader/log/data-loader.log

Creating Repository objects manually


The Repository creation scripts run locally on the Content Server machine. Before executing the
relevant script, copy the [Temporary BAM setup folder]\BAM Data Loader\ folder to the Content
66

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Installing the BAM Server on Oracle Application Server

Server machine.
To create the Repository objects:
1. Access one of the following folders:
Windows: [Temporary BAM setup folder]\BAM Data Loader\bin\
UNIX/Linux: [Temporary BAM setup folder]/BAM Data Loader/bin/
2. Run one of the following batch/shell files:
Windows: create-repo-objects.cmd
UNIX/Linux: create-repo-objects.sh
3. When prompted, provide the following Repository connection parameters on the command line:
repository name
login name (repository owner or administrator name)
password
When you run the create-repo-objects command, you get the following outputs:
run-api finished with errorlevel = 0
run-dql finished with errorlevel = 1
This output is normal.
4. Verify the results of running the SQL script by viewing the following log files in the BAM Data
Loader folder:
run-api.log
run-dql.log

Preparing the BAM server WAR file for


deployment
Perform the following procedure to prepare the BAM server WAR file for deployment.
To prepare the BAM server WAR file for deployment:
1. Create <Temporary WAR location> and the bam-server.war folder under it.
2. Access one of the following folders:
Windows: <Temporary BAM setup folder>\BAM Server\
UNIX/Linux: <Temporary BAM setup folder>/BAM Server/
3. Unpack the bam-server-oc4j-10.1.3.3.war file into the <Temporary WAR
location>\bam-server.war folder.
For instructions about unpacking the WAR file, see Unpacking WAR Files, page 109.
4. Move xpp3.jar from <Temporary WAR location>\bam-server.war\WEB-INF\lib to
<your_app_server_home>\applib.
5. Delete xpp3.jar from <Temporary WAR location>\bam-server.war\WEB-INF\lib.
6. If you are using an Oracle 10 or 11 BAM database, complete the steps below. Otherwise, proceed
to step 7.
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

67

Installing the BAM Server on Oracle Application Server

a. Delete the ojdbc14.jar file located in bam-server.war\WEB-INF\lib.


b. From the bam-product-supplemental_files.zip file you downloaded from the EMC Download
Center, open bam-product-supplemental_files\Oracle.

c. If you are using JDK 1.5, copy the ojdbc5.jar file to bam-server.war\WEB-INF\lib.
d. If you are using JDK 1.6, copy the ojdbc6.jar file to bam-server.war\WEB-INF\lib.
7. In <Temporary WAR location>\bam-server.war modify the dfc.properties file using instructions in
Enabling DFC connections to the Repository, page 58. Perform this procedure before attempting
to connect to Documentum repositories.
8. Modify the jdbc-config.xml file using instructions in Specifying BAM database connection
parameters, page 59.
9. Modify the dfc-config.xml file using instructions in Modifying DFC session properties, page 60.
10. Modify the log4j.properties file using instructions in Modifying the location of log files, page 60.
11. Create a deployment archive bam-server.war that includes all the updated configuration file
changes. Repack the bam-server.war file comprising the updated configuration files, and then
deploy the bam-server.war file on the Oracle 10g application.
For instructions about repacking the WAR file, see Repacking WAR Files, page 109.
Note: Externalizing BAM configuration files, page 115 is another approach used to configure the
BAM server.

Enabling DFC connections to the Repository


Connection broker values must be entered in dfc.properties before BAM is able to connect with a
Repository.
To enable DFC connections to the Repository:
1. Open the dfc.properties file available in one of the following paths where you unpacked the
WAR file:
Windows: [Temporary WAR location]\bam-server.war\WEB-INF\classes
UNIX/Linux: [Temporary WAR location]/bam-server.war/WEB-INF/classes
2. Perform one of the following tasks:

a. If you are installing the BAM server on the Content Server computer, replace
the first line of the dfc.properties file with the following statement:#include
[documentum_user_dir]\config\dfc.properties.

For example, specify the path to the dfc.properties file as follows: #include
C:\Documentum\config\dfc.properties.
b. If you are installing the BAM server on a computer other than the Content Server computer,
delete or comment the #include statement. Then, specify the required values for the following
parameters:
dfc.docbroker.host[0]=host_name
dfc.docbroker.port[0]=port_number
3. Save and close the dfc.properties file.
68

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Installing the BAM Server on Oracle Application Server

Specifying BAM database connection


parameters
BAM database connection parameters entered in jdbc-config.xml enable the BAM server to connect
to the BAM database.
To specify BAM database connection parameters:
1. Open the jdbc-config.xml file available in one of the following paths:
Windows: [Temporary WAR location\bam-server.war\WEB-INF\classes\config\
UNIX/Linux: [Temporary WAR location/bam-server.war/WEB-INF/classes/config/
2. Modify the following BAM database connection parameters with the relevant values by editing
the XML file. You can open the XML file using a standard file editor or an XML Editor. Modify
the following XML element values:
dialect For example, in the case of MS SQL, change <dialect>$C(BAM,
DCTM_BAM_DB_DIALECT)</dialect> to <dialect>mssql</dialect>
URL
driver
username
password
Use the RDBMS Type, Dialect, and Driver Class values specified in the following table, and
specify the Connection URL based on your RDBMS environment:
Table 9

BAM Database connection parameters and values

RDBMS
Type

Dialect

Driver Class

Connection URL

MS SQL

mssql

com.microsoft.com.microsoft.

jdbc:sqlserver://<HOST>:<PORT>;

sqlserver.jdbc.SQLServer
Driver

databasename=<DB.NAME>;
SELECTMETHOD=Cursor

Oracle

oracle

oracle.jdbc.driver.OracleDriver

jdbc:oracle:thin:@<HOST>:
<PORT>:<SID>

DB2

db2

com.ibm.db2.jcc.DB2Driver

jdbc:db2://<HOST>:<PORT>/
<DB.NAME>

3. Save and close the jdbc-config.xml file.

Modifying DFC session properties


Modify DFC session properties in dfc-config.xml to enable the BAM server to connect to the
Repository.
To modify DFC session properties:
1. Open dfc-config.xml available in one of the following paths:
Windows: [Temporary WAR location]\bam-server.war\WEB-INF\classes\config\
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

69

Installing the BAM Server on Oracle Application Server

UNIX/Linux: [Temporary WAR location]/bam-server.war/WEB-INF/classes/config/


2. Modify the following Repository properties displayed in bold and italicized font:
<session repository="
$C(BAM, DOCBASE_NAME)
">
<username>
$C(BAM, DOCBASE_USER)
</username>
<password encrypted="false">
$C(BAM, SECURE.DOCBASE_PASSWORD)
</password>
</session>

Note: SECURE.DOCBASE_PASSWORD is entered in clear text. The password is encrypted


after installation.
3. Save and close the dfc-config.xml file.

Modifying the location of log files


Modify the location of the log files by updating the log4j.properties file.
To modify the location of log files:
1. Open the log4j.properties file available in one of the following paths:
Windows: [Temporary WAR location]\bam-server.war\WEB-INF\classes
UNIX/Linux: [Temporary WAR location]/bam-server.war/WEB-INF/classes
2. Modify the location of the log files according to the log4j standards. If you leave the location of
the log files unchanged, the log files are directed to the home path of the application server.
3. Save and close the log4j.properties file.

Deploying the BAM application on the Oracle


application server
You can deploy the BAM application on the Oracle 10g application server using the Oracle Application
Server (OC4J) Administration Console. Follow the instructions listed in this section to deploy the
BAM application on the Oracle 10g application server.
CAUTION: After preparation is completed, repack the currently unpacked bam-server.war file.
To deploy the BAM application on the Oracle application server:
1. Start the Oracle 10g application server.
2. Open the Oracle 10g Application Server Administration Console.
The format of the URL is as follows: http://<host>:<port>/em/console.
The Login page is displayed.
70

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Installing the BAM Server on Oracle Application Server

3. Log on to the Administration Console.


4. Click the Applications tab.
5. Click Deploy.
6. In the Archive Location field, browse to the OC4J WAR file location ([Temporary WAR
location]\bam-server.war) or copy the full path of the file into the field.
7. Click Next.
8. In the Application Name field, enter bam-server.
9. In the Context Root field, enter bam-server.
10. Click Next.
11. In the Deployment Tasks list, select the Configure Class Loading task.
12. In the Configure Class Loading page, perform the following steps:

a. Clear the selection of the Inherit parent applications shared libraries imports option.
b. Select the Search Local Classes First option.
c. Click OK to continue.
13. Click Deploy.
The deployment process is initiated.
14. Click Return.
15. To verify whether the BAM application was installed successfully open the OC4J Administrator
Console in a browser using the following URL: http://<host>:<port>/em/console.
The default port number is 8888.
The OC4J Administrator Console is displayed.
16. In the Applications tab, select the bam-server application.

a. Select the bam-server web module.


17. Perform one of the following steps:

a. Select the Test Web Module option.


b. Browse to the following URL: http://<host>:<port>/bam-server.
If the BAM server is running, the BAM server Welcome page is displayed.

Recommended Oracle 10g application server


parameters settings
Change the Oracle 10g application server parameters as follows:
Initial Java heap size: 512 m
Maximum Java heap size: 1024m
Java threads stack size: 128k
Initial size for the permanent generation heap: 128m
Maximum size for the permanent generation heap: 256m
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

71

Installing the BAM Server on Oracle Application Server

Initial size of new generation pool: 128 m


Maximum size of new generation pool: 384m
Use parallel GC

Post-installation guidelines
Changing the default host and port from TaskSpace to
point to the BAM server URL
If the application server does not use port 8080 by default, then the BAM server port number must be
configured in the BAM Port field of the Administration tab of TaskSpace.
If the BAM server and TaskSpace are not installed on the same physical machine, change the BAM
Host URL from localhost to the IP address of the BAM server machine. This procedure is completed
in the Administration tab of TaskSpace.
For instructions, see the Configuring connection settings section of the Business Activity Monitor
Implementation Guide.

Installing preconfigured dashboard


You can now install the preconfigured dashboard, if necessary. For instructions, see Installing the
preconfigured dashboards, page 88.

72

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Chapter 9
Installing the BAM Server on Sun
Application Servers
This chapter discusses the following:

Overview of installing BAM on Sun application servers

Creating BAM database objects manually

Creating Repository objects manually

Preparing the BAM server WAR file for deployment

Enabling DFC connections to the Repository

Specifying BAM database connection parameters

Modifying DFC session properties

Modifying the location of log files

Deploying the BAM application on the Sun Application Servers

Recommended Sun application server parameters settings

Post-installation guidelines

Overview of installing BAM on Sun application


servers
This chapter describes the process of installing the BAM server manually on a machine where either
the Sun GlassFish 2.1 Application Server or the Sun Java System Application Server 8.2 is installed.
This installation assumes that the Content Server and BAM database are installed on one or more
different machines. Installing the BAM server requires the completion of the following tasks: proper
creation of the repository and database objects, and updating the BAM configuration files. Finally,
this chapter includes post-installation guidelines.
You must have the access rights of an administrator to perform the BAM server installation.
Note: For information about the platforms and application servers on which the BAM server can be
installed, see the Business Activity Monitor Release Notes.

Creating BAM database objects manually


Use the BAM Data Loader utility to create the BAM database and Repository objects (tables, types,
shipping data) manually, before you install the BAM server. You can also use this utility to clean the
BAM Repository and database objects when there are Repository- or database-related errors. This
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

73

Installing the BAM Server on Sun Application Servers

utility is installed as part of the BAM server installer for JBoss and also resides in bam-product.zip.
To create BAM database objects:
1. Access one of the following folders:
Windows: [Temporary BAM setup folder]\BAM Data Loader\bin\
UNIX/Linux: [Temporary BAM setup folder]/BAM Data Loader/bin/
2. Execute the following batch/shell files and when prompted, provide the BAM database connection
parameters on the command line:
For Microsoft SQL-Server:
Windows: create-db-objects-mssql.cmd
UNIX/Linux: create-db-objects-mssql.sh
For DB2 database:
Windows: create-db-objects-db2.cmd
UNIX/Linux: create-db-objects-db2.sh
For Oracle database:
Windows: create-db-objects-oracle.cmd
UNIX/Linux: create-db-objects-oracle.sh

The database connection parameters you must specify are as follows:


JAVA_HOME: Enter the Java runtime home path (Java JRE must exist on your computer).
For example: C:\Program Files\Java\jre1.6.
database user: Enter the name of the BAM database owner.
database password: Enter the password of the BAM database owner.
database host: Enter the host name or IP address of the database server.
database port: Enter the port of the database server.
database name: For Oracle: Enter the SID. For DB2 and SQL-Server: Enter the database
name.
CAUTION: When executing the database creation script you must make sure that the path to
the JRE entered in the command line is valid. If an invalid path is provided the creation script
fails, however, no error is provided in the log file. If you have any doubts about the validity of the
JRE path, check the BAM database to make sure that the objects were created.
3. Verify the results of running the SQL script by viewing the following log file in one of the
specified paths:
Windows: [Temporary BAM setup folder]\BAM Data Loader\log\data-loader.log
UNIX/Linux: [Temporary BAM setup folder]/BAM Data Loader/log/data-loader.log

Creating Repository objects manually


The Repository creation scripts run locally on the Content Server machine. Before executing the
relevant script, copy the [Temporary BAM setup folder]\BAM Data Loader\ folder to the Content
Server machine.
74

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Installing the BAM Server on Sun Application Servers

To create the Repository objects:


1. Access one of the following folders:
Windows: [Temporary BAM setup folder]\BAM Data Loader\bin\
UNIX/Linux: [Temporary BAM setup folder]/BAM Data Loader/bin/
2. Run one of the following batch/shell files:
Windows: create-repo-objects.cmd
UNIX/Linux: create-repo-objects.sh
3. When prompted, provide the following Repository connection parameters on the command line:
repository name
login name (repository owner or administrator name)
password
When you run the create-repo-objects command, you get the following outputs:
run-api finished with errorlevel = 0
run-dql finished with errorlevel = 1
This output is normal.
4. Verify the results of running the SQL script by viewing the following log files in the BAM Data
Loader folder:
run-api.log
run-dql.log

Preparing the BAM server WAR file for


deployment
Perform the following procedure to prepare the BAM server WAR file for deployment. Preparing the
BAM server WAR file for deployment includes unpacking the bam-server.war file, updating the
relevant configuration files, and repacking the bam-server.war file. These tasks are completed before
deploying the BAM server on either:
Sun GlassFish 2.1 Application Server
Sun Java System Application Server 8.2.

To prepare the BAM server WAR file for deployment:


1. Create [Temporary WAR location] and the bam-server.war folder under it.
2. Access one of the following folders:
Windows: [Temporary BAM setup folder]\BAM Server\
UNIX/Linux: [Temporary BAM setup folder]/BAM Server/
3. Unpack the bam-server.war file into the [Temporary WAR location]\bam-server.war folder.
For instructions about unpacking the WAR file, see Unpacking WAR Files, page 109.
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

75

Installing the BAM Server on Sun Application Servers

4. If you are using an Oracle 10 or 11 BAM database, complete the steps below. Otherwise, proceed
to step 5.

a. Delete the ojdbc14.jar file located in bam-server.war\WEB-INF\lib.


b. From the bam-product-supplemental_files.zip file you downloaded from the EMC Download
Center, open bam-product-supplemental_files\Oracle.

c. If you are using JDK 1.5, copy the ojdbc5.jar file to bam-server.war\WEB-INF\lib.
d. If you are using JDK 1.6, copy the ojdbc6.jar file to bam-server.war\WEB-INF\lib.
5. Modify the dfc.properties file using instructions in Enabling DFC connections to the Repository,
page 68. Perform this procedure before attempting to connect to Documentum repositories.
6. Modify the jdbc-config.xml file using instructions in Specifying BAM database connection
parameters, page 69.
7. Modify the dfc-config.xml file using instructions in Modifying DFC session properties, page 69.
8. Modify the log4j.properties file using instructions in Modifying the location of log files, page 70.
9. Create a deployment archive bam-server.warthat includes all the updated configuration file
changes.
10. Repack the bam-server.war file comprising the updated configuration files.
For instructions about repacking the WAR file, see Repacking WAR Files, page 109.
11. Deploy the bam-server.war file on either the Sun GlassFish 2.1 Application Server or the Sun
Java System Application Server 8.2.
Note: Externalizing BAM configuration files, page 115 is another approach used to configure the
BAM server.

Enabling DFC connections to the Repository


Connection broker values must be entered in dfc.properties before BAM is able to connect with a
Repository.
To enable DFC connections to the Repository:
1. Open the dfc.properties file available in one of the following paths where you unpacked the
WAR file:
Windows: [Temporary WAR location]\bam-server.war\WEB-INF\classes
UNIX/Linux: [Temporary WAR location]/bam-server.war/WEB-INF/classes
2. Perform one of the following tasks:

a. If you are installing the BAM server on the Content Server computer, replace
the first line of the dfc.properties file with the following statement:#include
[documentum_user_dir]\config\dfc.properties.

For example, specify the path to the dfc.properties file as follows: #include
C:\Documentum\config\dfc.properties.
b. If you are installing the BAM server on a computer other than the Content Server computer,
delete or comment the #include statement. Then, specify the required values for the following
parameters:
76

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Installing the BAM Server on Sun Application Servers

dfc.docbroker.host[0]=host_name
dfc.docbroker.port[0]=port_number
3. Save and close the dfc.properties file.

Specifying BAM database connection


parameters
BAM database connection parameters entered in jdbc-config.xml enable the BAM server to connect
to the BAM database.
To specify BAM database connection parameters:
1. Open the jdbc-config.xml file available in one of the following paths:
Windows: [Temporary WAR location\bam-server.war\WEB-INF\classes\config\
UNIX/Linux: [Temporary WAR location/bam-server.war/WEB-INF/classes/config/
2. Modify the following BAM database connection parameters with the relevant values by editing
the XML file. You can open the XML file using a standard file editor or an XML Editor. Modify
the following XML element values:
dialect For example, in the case of MS SQL, change <dialect>$C(BAM,
DCTM_BAM_DB_DIALECT)</dialect> to <dialect>mssql</dialect>
URL
driver
username
password
Use the RDBMS Type, Dialect, and Driver Class values specified in the following table, and
specify the Connection URL based on your RDBMS environment:
Table 10

BAM Database connection parameters and values

RDBMS
Type

Dialect

Driver Class

Connection URL

MS SQL

mssql

com.microsoft.com.microsoft.

jdbc:sqlserver://<HOST>:<PORT>;

sqlserver.jdbc.SQLServer
Driver

databasename=<DB.NAME>;
SELECTMETHOD=Cursor

Oracle

oracle

oracle.jdbc.driver.OracleDriver

jdbc:oracle:thin:@<HOST>:
<PORT>:<SID>

DB2

db2

com.ibm.db2.jcc.DB2Driver

jdbc:db2://<HOST>:<PORT>/
<DB.NAME>

3. Save and close the jdbc-config.xml file.

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

77

Installing the BAM Server on Sun Application Servers

Modifying DFC session properties


Modify DFC session properties in dfc-config.xml to enable the BAM server to connect to the
Repository.
To modify DFC session properties:
1. Open dfc-config.xml available in one of the following paths:
Windows: [Temporary WAR location]\bam-server.war\WEB-INF\classes\config\
UNIX/Linux: [Temporary WAR location]/bam-server.war/WEB-INF/classes/config/
2. Modify the following Repository properties displayed in bold and italicized font:
<session repository="
$C(BAM, DOCBASE_NAME)
">
<username>
$C(BAM, DOCBASE_USER)
</username>
<password encrypted="false">
$C(BAM, SECURE.DOCBASE_PASSWORD)
</password>
</session>

Note: SECURE.DOCBASE_PASSWORD is entered in clear text. The password is encrypted


after installation.
3. Save and close the dfc-config.xml file.

Modifying the location of log files


Modify the location of the log files by updating the log4j.properties file.
To modify the location of log files:
1. Open the log4j.properties file available in one of the following paths:
Windows: [Temporary WAR location]\bam-server.war\WEB-INF\classes
UNIX/Linux: [Temporary WAR location]/bam-server.war/WEB-INF/classes
2. Modify the location of the log files according to the log4j standards. If you leave the location of
the log files unchanged, the log files are directed to the home path of the application server.
3. Save and close the log4j.properties file.

Deploying the BAM application on the Sun


Application Servers
You can deploy the BAM application with the administration console that accompanies the Sun
GlassFish 2.1 Application Server and the Sun Java System Application Server 8.2.
78

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Installing the BAM Server on Sun Application Servers

To deploy the BAM application on the Sun application servers:


1. Upload the bam-server.war file to the host where either the Sun GlassFish 2.1 Application Server
or the Sun Java System Application Server 8.2 is installed.
2. Open the administrative console of the application server you are using. The format of the URL
is as follows: http://<host>:<port>.
The Welcome page is displayed.
3. In the Left pane, expand the Applications node, and click Enterprise Applications.
4. Click Deploy.
5. In the Type list box, select Web Application (.war).
6. Select the Local packaged file or directory that is accessible from the Application Server
radio button.
7. Browse to the folder that contains the WAR file.
8. In the Virtual Server list box, select server.
As an optional step, you can enter a description in the Description field.
9. Click OK.
10. Restart the Sun application server.
11. Browse to the bam-server URL to verify whether the BAM server is up and running. For example,
browse to http://<BAM server IP/machine name>:<port>/bam-server/.
If the BAM server is running, the BAM server Welcome page is displayed.

Recommended Sun application server


parameters settings
Change the Sun application server parameters as follows:
Initial Java heap size: 512 m
Maximum Java heap size: 1024m
Use parallel GC:
Number of threads used by parallel GC: 20

Post-installation guidelines
Changing the default host and port from TaskSpace to
point to the BAM server URL
If the application server does not use port 8080 by default, then the BAM server port number must be
configured in the BAM Port field of the Administration tab of TaskSpace.
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

79

Installing the BAM Server on Sun Application Servers

If the BAM server and TaskSpace are not installed on the same physical machine, change the BAM
Host URL from localhost to the IP address of the BAM server machine. This procedure is completed
in the Administration tab of TaskSpace.
For instructions, see the Configuring connection settings section of the Business Activity Monitor
Implementation Guide.

Installing preconfigured dashboard


You can now install the preconfigured dashboard, if necessary. For instructions, see Installing the
preconfigured dashboards, page 88.

80

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Chapter 10
Configuring Business Activity Monitor
This chapter discusses the following:

Overview of configuration

Configuring connection settings

Activating process monitoring

Overview of configuration
BAM configuration refers to a set of features that enable process execution data to be collected,
formatted, and aggregated by the BAM server. Process administrators must make sure that a
connection with the BAM server is established. This connection allows monitoring to be activated.
Note: Refer to chapter 3 of the Documentum Business Activity Monitor 6.7 Implementation Guide for
additional configuration steps including turning the Audit Trail on, and making SDTs and package
object types reportable.

Configuring connection settings


The BAM server interacts with TaskSpace, the dashboard, and Process Builder. BAM dashboards
request reports from the BAM server. Similarly, Process Builder communicates to the BAM server
when business data is monitored. Each of these clients connects with the BAM server. To help with
this connection, the BAM server publishes its address to a specific Content Server object. The client
applications read this address. Configuring connection settings involves entering BAM host and port
numbers.
To configure BAM connection settings:
1. Log in to TaskSpace.
2. Select the Administration tab.
3. From the left tree menu select Server Management > Business Activity Monitoring > Data
Transfer Settings.
4. Within the Connection region at the bottom of the form, enter the BAM Host URL.
The BAM Host URL is the machine on which the BAM server is deployed.
5. In the BAM Port field enter the BAM server port number.
6. Click OK at the bottom of the form.
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

81

Configuring Business Activity Monitor

Activating process monitoring


Activating monitoring turns on all jobs completed by the BAM server. These BAM server jobs include
the event pipe process, the format, aggregation and alert engines, and purging jobs.
To activate process monitoring:
1. Log in to TaskSpace.
2. Click the Administration tab.
3. Select Server Management from the left tree menu.
4. Click the Business Activity Monitor Activate button.
The Status: changes from Stopped to Running.

82

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Chapter 11
Installing Process Reporting Services
This chapter discusses the following:

Overview of PRS and Crystal Reports installation

PRS Client system requirements

Installing the Process Reporting Services Client

Logging in to PRS

Installing Crystal Reports

I18N Notes

Overview of PRS and Crystal Reports


installation
Process Reporting Services (PRS) is an Eclipse-based component that allows a designer to create
BAM reports, charts, and alerts. PRS offers a drag-and-drop capability for defining data sources. Data
sources defined in Process Reporting Services can be exported to Crystal Reports for report design.
One user seat of Crystal Reports is packaged with every license of BAM. However, you can install as
many seats of Process Reporting Services as needed.
You can install the PRS Client automatically using the BAM server installer, or copy the PRS
executable file to any machine and run it.

PRS Client system requirements


This section contains a table that outlines PRS system requirements.
Table 11

PRS Client System Requirements

System Component

Requirement

Platform

IBM PC or compatible with Pentium 1.26 GHz processor

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

83

Installing Process Reporting Services

System Component

Requirement

Software

Adobe Flash Player 9.x, 10.x


Adobe SVG Viewer 3.x

Note: SVG Viewer 3.x must be installed on the machine


of a user if Internet Explorer is used. SVG is natively
supported by Firefox and other browsers. Although Adobe
Systems SVG Viewer underwent end-of-life in January of
2009, it continues to be available for download. For more
information about SVG Viewers end-of-life, please see
http://www.adobe.com/svg/pdfs/ASV_EOL_FAQ.pdf.
Memory

At least 1 GB of RAM

Network

Network card that supports TCP/IP and network access to the


Server Account

Disk Space

Crystal Reports Designer requires at least 1 GB of disk space

Operating system

Windows XP SP3 (32-bit version)


Windows Vista SP1 (32-bit version)
Windows Server 2003 R2 with SP2 (32-bit version)
Windows Server 2003 SP2 (32-bit version)
Windows Server 2008 (32-bit version)

Business objects Crystal Reports

Crystal Reports 2008

Note: PRS is shipped with JRE Version 1.6. When installing PRS use the same Java vendor and
version that is used on the BAM server. To make these versions consistent change the Java version that
works with PRS. Changing the version of Java is completed by replacing the contents of the <PRS
Installation>\jre with the new version of Java.

Installing the Process Reporting Services Client


You must have the Windows administrator access rights to perform the PRS client installation.
This section provides instructions to install the PRS Client. JAVA Run Time Environment (JRE) is
installed as part of the client installation. Do not install the JRE separately.
To install the Process Reporting Services Client:
1. Create [PRS target folder].
2. Access the [Temporary BAM setup folder]\PRS\ folder on the machine where you unpacked
the bam-product.zip file.
3. Unpack the [Temporary BAM setup folder]\PRS\PRS-win32.win32.x86.zip file into [PRS target
folder].
The following folders and files are unpacked into [PRS target folder]:
configuration
84

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Installing Process Reporting Services

jre
plugins
eclipseproduct
PRS.exe
PRS.ini

Logging in to PRS
Start the BAM server before logging in to PRS. The BAM server must be started first because PRS
consumes services provided by the BAM server.
To log in to PRS:
1. Access [PRS target folder].
2. Run PRS.exe.
The PRS Client Login dialog box is displayed.
3. Click Connect.
The Server Host Configuration dialog box is displayed.
4. Enter the Host URL.
The URL must be entered because PRS consumes services provided by the BAM server. The URL
must be specified in this format: http://<host>:<port>/bam-server
Note: The default port for the Java Method Server is 9080. Change the port when you connect
from PRS to the BAM server for the first time, if you deployed the BAM server on JMS.
5. Click OK.
6. Specify the login credentials.
7. Click OK.

Installing Crystal Reports


You must have the Windows administrator access rights to perform the Crystal Reports installation.
This section provides instructions for installing Crystal Reports.
To install Crystal Reports:
1. You can obtain a valid license key of Crystal Reports from the EMC download center.
2. Access the local folder where you downloaded the Crystal_Designer_XI_R2_SP2.zip file, and
unpack it into a temporary location.
3. From the temporary location, run 14-00806-085.part1.exe and follow the on-screen instructions
to complete the Crystal Reports installation.
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

85

Installing Process Reporting Services

I18N Notes
East Asian language fonts must be installed on the Windows platform, in order for users to work with
the PRS client in the Japanese, Korean, and Chinese languages.
To install East Asian fonts:
1. In the Control Panel, double-click Regional and Language Options.
2. Click the Languages tab, and select the Install files for East Asian languages option.
3. Click Apply.
4. Click OK.
Ensure that the database is installed with the Unicode character set.

86

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Chapter 12
Installing the Preconfigured
Dashboards
This chapter discusses the following:

Overview of preconfigured dashboard installation

Prerequisites for installing the preconfigured dashboard

Installing the preconfigured dashboards

Overview of preconfigured dashboard


installation
If you manually installed the BAM server on an application server, then you can manually install the
preconfigured dashboards. Ignore the instructions in this chapter if you installed BAM using the BAM
Installer, which installs the preconfigured dashboard by default.
This chapter provides guidance to install the preconfigured dashboard. The installation of the
preconfigured dashboard consists of installing the following components:
DQL script
DAR file
Note: BAM 6.7 ships with a set of preconfigured dashboards that are installed.

Prerequisites for installing the preconfigured


dashboard
Perform the following tasks before installing the preconfigured dashboards:
Install the BAM server. For instructions, see the Installing BAM on the Java Method Server using
the installer, page 25 chapter or one of the following:
Overview of installing BAM on Red Hat JBoss, page 31
Overview of installing BAM on Apache Tomcat, page 39
Overview of installing BAM on Oracle WebLogic, page 47
Overview of installing BAM on WebSphere, page 55
Overview of installing BAM on Oracle application servers, page 65
Overview of installing BAM on Sun application servers, page 73
Install TaskSpace using the DAR file, and not the DocApp. For instructions, see the TaskSpace
Deployment Guide.
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

87

Installing the Preconfigured Dashboards

Note: Install the Process Engine before you install the TaskSpace DAR. For instructions, see the
Process Engine Installation Guide.

Installing the preconfigured dashboards


Follow the instructions provided in this section to locate and install the preconfigured dashboards
DAR file. After you have installed the preconfigured dashboard, you can log in to PRS and open the
Preconfigured Dashboard report category. All preconfigured dashboard reports are saved in their
own category.
To install the preconfigured dashboards:
1. Locate the PreConfiguredDashboard.dar file in bam-product.zip/BAM
Installer/BAM_Installer_JBoss_win.zip/dars.jar/.
2. Install the PreConfiguredDashboard.dar file on the target repository using the Composer
DAR installer.
For instructions on installing the DAR file, see the Documentum Composer User Guide.
3. Restart the BAM server.
Note: After installing the preconfigured dashboards, add the new dashboards (process monitor, process
summary, and the alert monitor) to the BAM 6.7 application. For instructions on adding existing
dashboards, see the Adding existing dashboards section of the TaskSpace Configuration Guide.

88

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Chapter 13
Upgrading Business Activity Monitor
from 6.5 to 6.5 SP1
This chapter discusses the following:

Overview of upgrading from BAM version 6.5 to 6.5 SP1

Upgrading BAM Repository and BAM database

Overview of upgrading from BAM version 6.5


to 6.5 SP1
This chapter contains instructions for upgrading Business Activity Monitor (BAM) from 6.5 to 6.5
SP1. Review the contents of the Business Activity Monitor 6.5 SP1 Release Notes for information about
the application servers, browsers, and other software in the environments that are certified for BAM.
The migration of the BAM 6.5 implementation to BAM 6.5 SP1 comprises the following tasks in
the specified sequence:
1. Upgrading Forms Builder, Process Builder, and TaskSpace from version 6.5 to version 6.5 SP1.
2. Upgrading BAM Repository and BAM database.

Upgrading BAM Repository and BAM database


This section contains instructions for upgrading the BAM repository and database from version 6.5 to
version 6.5 SP1. Perform the following steps in one of the following folders:
Windows: [Temporary BAM setup folder]\BAM Data Loader\bin\
UNIX/Linux: [Temporary BAM setup folder]/BAM Data Loader/bin/
1. To upgrade the existing BAM Repository:

a. Configure the Repository parameters in dfc.properties.


b. Run one of the following commands:
Windows: upgrade-repository-D6.5_D6.5-SP1.cmd
UNIX/Linux: upgrade-repository-D6.5_D6.5-SP1.sh
2. To upgrade the existing BAM database:

a. Configure database connection parameters in data-loader.properties. Understanding how to


update the data-loader.properties file, page 111 provides more information about the BAM
database connection parameters in the data-loader.properties file.
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

89

Upgrading Business Activity Monitor from 6.5 to 6.5 SP1

b. Run one of the following commands:


Windows: upgrade-db-D6.5_D6.5-SP1.cmd
UNIX/Linux: upgrade-db-D6.5_D6.5-SP1.sh
3. Verify that the upgrade was successful by reviewing the following log file for errors:<Documentum
Installation Directory>\bam\sql-loader\log
Install the BAM server, or deploy the BAM 6.5 SP1 server WAR or EAR file on the application
server with which you are working:
Installing BAM on the Java Method Server using the installer, page 25
Overview of installing BAM on Red Hat JBoss, page 31
Overview of installing BAM on Apache Tomcat, page 39
Overview of installing BAM on Oracle WebLogic, page 47
Overview of installing BAM on WebSphere, page 55
Overview of installing BAM on Oracle application servers, page 65

90

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Chapter 14
Upgrading Business Activity Monitor
from 6.5 SP1 to 6.5 SP2
This chapter discusses the following:

Overview of upgrading from BAM version 6.5 SP1 to 6.5 SP2

Upgrading BAM Repository and BAM database

Overview of upgrading from BAM version 6.5


SP1 to 6.5 SP2
This chapter contains instructions for upgrading Business Activity Monitor (BAM) from 6.5 SP1 to 6.5
SP2. Review the contents of the Business Activity Monitor 6.5 SP2 Release Notes for information about
the application servers, browsers, and other software in the environments that are certified for BAM.
The migration of the BAM 6.5 SP1 implementation to BAM 6.5 SP2 comprises the following tasks in
the specified sequence:
1. Upgrading Forms Builder, Process Builder, and TaskSpace from version 6.5 SP1 to version 6.5 SP2.
2. Upgrading BAM Repository and BAM database.

Upgrading BAM Repository and BAM database


This section includes instructions for upgrading BAM from version 6.5 SP1 to version 6.5 SP2.
Perform the following steps in one of the following folders:
Windows: [Temporary BAM setup folder]\BAM Data Loader\bin\
UNIX/Linux: [Temporary BAM setup folder]/BAM Data Loader/bin/
1. To upgrade the existing BAM Repository:

a. Configure the Repository parameters in dfc.properties.


b. Run one of the following commands:
Windows: upgrade-repository-D6.5-SP1_D6.5-SP2.cmd
UNIX/Linux: upgrade-repository-D6.5-SP1_D6.5-SP2.sh
2. To upgrade the existing BAM database:

a. Configure database connection parameters in data-loader.properties. Understanding how to


update the data-loader.properties file, page 111 provides more information about the BAM
database connection parameters in the data-loader.properties file.
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

91

Upgrading Business Activity Monitor from 6.5 SP1 to 6.5 SP2

b. Run one of the following commands:


Windows: upgrade-db-D6.5-SP1_D6.5-SP2.cmd
UNIX/Linux: upgrade-db-D6.5-SP1_D6.5-SP2.sh
3. Verify that the upgrade was successful by reviewing the following log file for errors:
<Documentum Installation Directory>\bam\sql-loader\log
Install the BAM server, or deploy the BAM 6.5 SP2 server WAR or EAR file on the application
server with which you are working:
Installing BAM on the Java Method Server using the installer, page 25
Overview of installing BAM on Red Hat JBoss, page 31
Overview of installing BAM on Apache Tomcat, page 39
Overview of installing BAM on Oracle WebLogic, page 47
Overview of installing BAM on WebSphere, page 55
Overview of installing BAM on Oracle application servers, page 65
Overview of installing BAM on Sun application servers, page 73

92

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Chapter 15
Upgrading Business Activity Monitor
from 6.5 SP2 to 6.6
This chapter discusses the following:

Overview of upgrading from BAM version 6.5 SP2 to 6.6

Upgrading BAM Repository and BAM database

Overview of upgrading from BAM version 6.5


SP2 to 6.6
This chapter contains instructions for upgrading Business Activity Monitor (BAM) from 6.5 SP2 to
6.6. Review the contents of the Business Activity Monitor 6.6 Release Notes for information about the
application servers, browsers, and other software in the environments that are certified for BAM.
The migration of the BAM 6.5 SP2 implementation to BAM 6.6 comprises the following tasks in
the specified sequence:
1. Upgrading Forms Builder, Process Builder, and TaskSpace from version 6.5 SP2 to version 6.6.
2. Upgrading BAM Repository and BAM database.

Upgrading BAM Repository and BAM database


This section includes instructions for upgrading BAM from version 6.5 SP2 to version 6.6. Perform
the following steps in one of the following folders:
Windows: [Temporary BAM setup folder]\BAM Data Loader\bin\
UNIX/Linux: [Temporary BAM setup folder]/BAM Data Loader/bin/
1. To upgrade the existing BAM Repository:

a. Configure the Repository parameters in dfc.properties.


b. Configure the Repository parameters in data-loader.properties. Understanding how to update
the data-loader.properties file, page 111 describes how to use the data-loader.properties file.

c. Run one of the following commands:


Windows: upgrade-repository-D6.5-SP2_D6.6.cmd
UNIX/Linux: upgrade-repository-D6.5-SP2_D6.6.sh
2. To upgrade the existing BAM database:

a. Configure database connection parameters in data-loader.properties. Understanding how to


update the data-loader.properties file, page 111 describes how to use the data-loader.properties
file.
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

93

Upgrading Business Activity Monitor from 6.5 SP2 to 6.6

b. Run one of the following commands:


Windows: upgrade-db-D6.5-SP2_D6.6.cmd
UNIX/Linux: upgrade-db-D6.5-SP2_D6.6.sh
3. Verify that the upgrade was successful by reviewing the following log file for errors: <Temporary
BAM setup folder>\data-loader\log.
Install the BAM server, or deploy the BAM 6.6 server WAR or EAR file on the application server
with which you are working:
Installing BAM on the Java Method Server using the installer, page 25
Overview of installing BAM on Red Hat JBoss, page 31
Overview of installing BAM on Apache Tomcat, page 39
Overview of installing BAM on Oracle WebLogic, page 47
Overview of installing BAM on WebSphere, page 55
Overview of installing BAM on Oracle application servers, page 65
Overview of installing BAM on Sun application servers, page 73

94

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Chapter 16
Upgrading Business Activity Monitor
from 6.6 to 6.7
This chapter discusses the following:

Overview of upgrading from BAM version 6.6 to 6.7

Upgrading BAM Repository and BAM database

Overview of upgrading from BAM version 6.6


to 6.7
This chapter contains instructions for upgrading Business Activity Monitor (BAM) from 6.6 to 6.7.
Review the contents of the Business Activity Monitor 6.7 Release Notes for information about the
application servers, browsers, and other software in the environments that are certified for BAM.
The migration of the BAM 6.6 implementation to BAM 6.7 comprises the following tasks:
1. Upgrading Forms Builder, Process Builder, and TaskSpace from version 6.6 to version 6.7.
2. Upgrading BAM Repository and BAM database.

Upgrading BAM Repository and BAM database


This section includes instructions for upgrading BAM from version 6.6 to version 6.7. Perform the
following steps in one of the following folders:
Windows: [Temporary BAM setup folder]\BAM Data Loader\bin\
UNIX/Linux: [Temporary BAM setup folder]/BAM Data Loader/bin/
1. To upgrade the existing BAM Repository:

a. Configure the Repository parameters in dfc.properties.


b. Configure the Repository parameters in data-loader.properties. Understanding how to update
the data-loader.properties file, page 111 describes how to use the data-loader.properties file.

c. Run one of the following commands:


Windows: upgrade-repository-D6.6_D6.7.cmd
UNIX/Linux: upgrade-repository-D6.6_D6.7.sh
2. To upgrade the existing BAM database:

a. Configure database connection parameters in data-loader.properties. Understanding how to


update the data-loader.properties file, page 111 describes how to use the data-loader.properties
file.
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

95

Upgrading Business Activity Monitor from 6.6 to 6.7

b. Run one of the following commands:


Windows: upgrade-db-D6.6_D6.7.cmd
UNIX/Linux: upgrade-db-D6.6_D6.7.sh
3. Verify that the upgrade was successful by reviewing the following log file for errors: <Temporary
BAM setup folder>\data-loader\log.
Install the BAM server, or deploy the BAM 6.7 server WAR or EAR file on the application server
with which you are working:
Installing BAM on the Java Method Server using the installer, page 25
Overview of installing BAM on Red Hat JBoss, page 31
Overview of installing BAM on Apache Tomcat, page 39
Overview of installing BAM on Oracle WebLogic, page 47
Overview of installing BAM on WebSphere, page 55
Overview of installing BAM on Oracle application servers, page 65
Overview of installing BAM on Sun application servers, page 73

96

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Chapter 17
Upgrading BAM Artifacts
This chapter discusses the following:

Upgrading BAM artifacts from version 6.5 and 6.5 SP1 to version 6.6

Upgrading BAM artifacts from version 6.5 SP2 to version 6.6

Upgrading BAM artifacts from version 6.6 to version 6.7

Upgrading BAM artifacts from version 6.5 and


6.5 SP1 to version 6.6
Documentum Composer is used to upgrade BAM application configuration settings and reports from
version 6.5 and 6.5 SP1 to version 6.6. BAM dashboards are also a BAM application artifact, but
these are upgraded when a TaskSpace application is upgraded. For more information on upgrading
a TaskSpace application, see the Documentum TaskSpace Deployment Guide. This section contains
instructions on using Documentum Composer Version 6.6 to upgrade BAM configuration settings and
reports from version 6.5 or version 6.5 SP1 to version 6.6. In this procedure a DAR is generated
using Composer, which is then installed into a new environment using the DAR Installer. Generating
and the installing a DAR is not the only method for upgrading BAM artifacts. BAM artifacts can
also be upgraded by importing them into a Composer project, and then installing them onto a target
environment from within Composer.
Note: This upgrade procedure does not upgrade the BAM database or repository.
To upgrade BAM artifacts from version 6.5 and 6.5 SP1 to 6.6:
1. Run the following script against the 6.5 or 6.5 SP1 Documentum repository:
alter type bami_rg_report_entity_field add fixed_order integer
go
update bami_rg_report_entity_field objects set fixed_order=column_order
go

Note: The bami_rg_report_entity_field type has changed in version 6.6. This field type must be
changed in the original repository before attempting to package the DAR.
2. Open Documentum Composer version 6.6.
3. From the Preferences menu select Java > Installed JREs.
The Edit JRE window opens.
4. Click the Directory button to locate and then select the JRE to be edited.
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

97

Upgrading BAM Artifacts

5. In the Default VM arguments field enter -Dbam.65.report.migration=1.


6. Click Finish.
The Edit JRE window closes.
7. Archive the BAM 6.5 or 6.5 SP1 artifacts using Composer 6.6 to generate a custom DAR file.
8. Open the Edit JRE window and remove -Dbam.65.report.migration=1 from the Default VM
arguments field.
9. Shut down the BAM server.
10. Install the custom DAR file in the 6.6 environment using the DAR Installer 6.6.
11. Restart the BAM server.

Upgrading BAM artifacts from version 6.5 SP2


to version 6.6
Documentum Composer is used to upgrade BAM application configuration settings and reports from
version 6.5 SP2 to version 6.6. BAM dashboards are also a BAM application artifact, but these are
upgraded when a TaskSpace application is upgraded. For more information on upgrading a TaskSpace
application, see the Documentum TaskSpace Deployment Guide. This section contains instructions on
using Documentum Composer Version 6.6 to upgrade BAM configuration settings and reports from
version 6.5 SP2 to version 6.6. In this procedure a DAR is generated using Composer, which is then
installed into a new environment using the DAR Installer. Generating and the installing a DAR is not
the only method for upgrading BAM artifacts. BAM artifacts can also be upgraded by importing them
into a Composer project, and then installing them onto a target environment from within Composer.
Note: This upgrade procedure does not upgrade the BAM database or repository.

To upgrade BAM artifacts from version 6.5 SP2 to 6.6:


1. Run the following script against the 6.5 SP2 Documentum repository:
alter type bami_rg_report_entity_field add fixed_order integer
go
update bami_rg_report_entity_field objects set fixed_order=column_order
go

Note: The bami_rg_report_entity_field type has changed in version 6.6. This field type must be
changed in the original repository before attempting to package the DAR.
2. Open Documentum Composer version 6.6.
3. Archive the BAM 6.5 SP2 artifacts using Composer 6.6 to generate a custom DAR file.
4. Shut down the BAM server.
5. Install the custom DAR file in the 6.6 environment using the DAR Installer 6.6.
6. Restart the BAM server.
98

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Upgrading BAM Artifacts

Upgrading BAM artifacts from version 6.6 to


version 6.7
Documentum Composer is used to upgrade BAM application configuration settings and reports from
version 6.6 to version 6.7. BAM dashboards are also a BAM application artifact, but these are
upgraded when a TaskSpace application is upgraded. For more information on upgrading a TaskSpace
application, see the Documentum TaskSpace Deployment Guide. This section contains instructions on
using Documentum Composer Version 6.7 to upgrade BAM configuration settings and reports from
version 6.6 to version 6.7. In this procedure a DAR is generated using Composer, which is then
installed into a new environment using the DAR Installer. Generating and the installing a DAR is not
the only method for upgrading BAM artifacts. BAM artifacts can also be upgraded by importing them
into a Composer project, and then installing them onto a target environment from within Composer.
Note: This upgrade procedure does not upgrade the BAM database or repository.

To upgrade BAM artifacts from version 6.6 to 6.7:


1. Open Documentum Composer version 6.7.
2. Archive the BAM 6.6 artifacts using Composer 6.7 to generate a custom DAR file.
3. Shut down the BAM server.
4. Install the custom DAR file in the 6.7 environment using the DAR Installer 6.7.
5. Restart the BAM server.

Multi-drill-down feature work around when upgrading


from TaskSpace 6.6 to 6.7
The dashboard multi-drill-down mechanism uses predefined filter expressions for events. The same
filter expression is used for all reports. A problem occurs when different reports use different tokens
for same the filter. For example, process list reports use STD.INSTANCE-ID, while SDT reports use
CAL.INSTANCE-ID. This issue has been fixed for all new installations of TaskSpace. However, if
you are upgrading from TaskSpace Version 6.6 to TaskSpace Version 6.7 this issue is still relevant and
you must update the dashboard xml file manually. Dashboards designed in TaskSpace Version 6.7 do
not required user intervention. Updating the dashboard xml file is only required when:
a dashboard is defined in TaskSpace Version 6.6 and prior, and
a multi-drill-down report is designed with an SDT
To update the dashboard xml file:
1. Retrieve the dashboard configuration xml file from the repository.
2. Open the xml file.
3. Locate the dashlet definition containing the name of the report. The name of the report is contained
in the contentName parameter.
<dashlet id="11 scheduler="0"
<metadata type="vertical" width="931"

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

99

Upgrading BAM Artifacts

percentWidth="1040"
height="361" percentHeight="1050"/>
<states>
<state event="no_state" dashletId="11"
contentId="0800002d80018455" contentName="SDT Report"
reportPath="/System/BAM/Report Categories/my_reports"
contentType="html" reportType="3" contentFormat="PIE3D"
isDefault="true"/>

4. Add the report base entity symbol to the report definition.


<dashlet id="11 scheduler="0"
<metadata type="vertical" width="931"
percentWidth="1040"
height="361" percentHeight="1050"/>
<states>
<state event="no_state" dashletId="11"
contentId="0800002d80018455" contentName="SDT Report"
reportPath="/System/BAM/Report Categories/my_reports"
contentType="html" reportType="3" contentFormat="PIE3D"
isDefault="true"
baseEntity=SDT/>

5. Save the dashboard xml back to the repository with the same dashboard ID.

100

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Chapter 18
Installation Verification
This chapter discusses the following:

Installation Verification

Installation Verification
Each of the manual installations tracks the progress of the installation and writes errors to three
different log files. These log files can be opened and used to verify that BAM has installed successfully.
In general, always search for the word Error in each log file. Error messages indicate that BAM has
not installed successfully. If you know or suspect that BAM has not installed correctly, then follow the
instructions in Dropping object types and tables from a BAM database, page 107.
The rest of this chapter includes the location of each installation log file. It also contains a description
of what to look for as evidence of a successful installation of BAM. The log files are:
data-loader.log
Location:
Windows: [Temporary BAM setup folder]\BAM Data Loader\log
UNIX:/Linux: [Temporary BAM setup folder]/BAM Data Loader/log
What to look for: Make sure that there are no Error messages.
run-api.log
Location:
Windows: [Temporary BAM setup folder]\BAM Data Loader\log
UNIX:/Linux: [Temporary BAM setup folder]/BAM Data Loader/log
What to look for: Make sure that there are no Error messages. The log file output pattern
approximates the following:
run-api.log pattern

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

101

Installation Verification

run-dql.log
Location:
Windows: [Temporary BAM setup folder]\BAM Data Loader\log
UNIX:/Linux: [Temporary BAM setup folder]/BAM Data Loader/log
What to look for: Make sure that there are no Error messages. Messages about connecting to a
repository and creating objects are written to the log file. The log file output pattern approximates
the following:
run-dql.log pattern

102

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Chapter 19
Uninstalling BAM
This chapter discusses the following:

Manually uninstalling BAM

Manually uninstalling BAM


Complete the following procedure to uninstall BAM.
To manually uninstall BAM:
1. Undeploy the BAM server from the application server you are using.
2. Drop all BAM database and repository objects. See Dropping object types and tables from a
BAM database, page 107 for guidance.
3. Delete all BAM files and folders. This includes, but is not limited to bam-server.war, all hotfixes,
the Data Loader, and PRS.

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

103

Uninstalling BAM

104

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Chapter 20
Clustering Business Activity Monitor
This chapter discusses the following:

Clustering Business Activity Monitor

Clustering Business Activity Monitor


The BAM server can be deployed across a cluster of application servers. One cluster is dedicated to
the TaskSpace web application layer, and another cluster is dedicated to the BAM application layer. In
an xCP clustered deployment, a load balancer is deployed in from of the TaskSpace application and
another load balancer is deployed between TaskSpace and the BAM servers cluster.
Note: BAM engine services (include the piping and formatting jobs) run on only one server instance
within a cluster. The first server started in the cluster runs the BAM engine services. To monitor BAM
engine performance, refer to the bam-engine.log file located on this particular server.
Clustering BAM involves:
Deploying the same BAM EAR or WAR file into multiple application servers.
Configuring load balancers in front of TaskSpace and the BAM server.
Configuring the load balancer in front of BAM to work with a sticky session.
When entering the BAM server IP address in TaskSpace, you must enter the IP address of the load
balancer deployed in front of the BAM server cluster.

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

105

Clustering Business Activity Monitor

106

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Chapter 21
Troubleshooting
This chapter discusses the following:

Dropping object types and tables from a BAM database

Dropping object types and tables from a BAM


database
BAM is shipped with scripts that allow you to drop all tables from a BAM database, or drop only
BAM object types from a repository. These methods are used if the BAM installation has failed, or if
you have doubts about the validity of the BAM repository objects.
Two cleanup scripts are provided for each method, one for a Windows environment and one for a Unix
environment. The scripts are located in <BAM Installation Files>\data-loader\bin\. These scripts
are run before the BAM creation scripts are run again.
Note: It is also possible to purge execution and aggregation data only, without disturbing object types or
other BAM database tables. This method is addressed in the Purging BAM execution and aggregation
tables section of the Administrating BAM Deployments chapter in the BAM Implementation Guide.
CAUTION: Dropping object types and tables is a BAM administrative procedure. If the BAM
database contains any process execution data, backup the BAM database.

To drop object types and tables from a BAM database:


1. Before either cleanup script is run, update the repository connection parameters in the
data-loader.properties file. The data-loader.properties file is located in the \data-loader\bin.
2. Within the BAM installation files you downloaded from the EMC Download Center, navigate to
<BAM Installation Files>\data-loader\bin\.
3. Perform one of the following:
To drop all tables in a Windows environment, run cleanup-db-objects.cmd.
To drop all tables in a Unix environment, run cleanup-db-objects.sh.
To drop BAM object types in a Windows environment, run cleanup-repo-objects.cmd.
To drop BAM object types in a Unix environment, run cleanup-repo-objects.sh.
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

107

Troubleshooting

108

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Appendix A
Working with WAR and EAR Files

This appendix contains the following:

Unpacking WAR Files

Repacking WAR Files

Unpacking WAR Files


1. Open the command prompt and navigate to the folder that contains the WAR file.
2. Create a folder named [Temporary WAR location].
3. Go up one level to the folder that contains the WAR file.
4. Right-click the WAR file you want to unpack and select Open With > WinZip.
5. Unpack the WAR file to the temporary location [Temporary WAR location].
To configure your computer to treat WAR files as ZIP files:

a. Go to the Control Panel.


b. Double-click Folder Options.
The Folder Options dialog box is displayed.
c. Click the File Types tab.
d. Navigate to the WAR extension in the Registered file types list.
e. Click Change.
The Open With dialog box is displayed.
f. Select WinZip in the Programs list.
g. Click OK.
h. Click Apply.
i. Click OK.

Repacking WAR Files


1. Access one folder level above [Temporary WAR location].
2. Change the directory to [Temporary WAR location].
Note: It is important for the directory structure to be the same as the original .WAR file.

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

109

Repacking WAR Files

3. Perform the following:

a. Select all objects in the folder.


b. Right-click the selected objects.
c. Select WinZip > Add to Zip.
4. In the Add to archive field of the Add dialog box, specify the name of the .WAR file you are
repacking.
5. Click Add.
The .WAR file is created.

110

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Appendix B
Working with the data-loader.properties
file

This appendix contains the following:

Understanding how to update the data-loader.properties file

Understanding how to update the


data-loader.properties file
The data-loader.properties file is used to upgrade BAM from:
version 6.5 to 6.5 SP1
version 6.5 SP1 to version 6.5 SP2
version 6.5 SP2 to version 6.6
version 6.6 to version 6.7
The data-loader.properties file contains parameters that establish connections to the BAM database
and the Documentum repository. The BAM database connections are listed first, followed by the
Documentum repository connection parameters.
Note: When upgrading from version 6.5 to 6.5 SP1 or from version 6.5 SP1 to 6.5 SP2, only the BAM
database parameters are required. For these upgrades, the Documentum repository upgrades by way of
the dfc.properties file only. When upgrading from version 6.5 SP2 to 6.6 or from version 6.6 to 6.7,
both the BAM database parameters and the Documentum repository parameters apply.
Before running the upgrade scripts, update the data-loader.properties file with BAM database and
Documentum repository connection parameters. The following table lists the BAM database properties
entered in the data-loader.properties file:
Table B.12

BAM database connection parameters

Property

Description

bam.db.dialect

Enter the BAM database dialect. oracle, mssql, and db2 are valid
values.

bam.db.url

Enter the JDBC URL of the BAM database.

bam.db.driver

Enter the JDBC driver associated with the database.

bam.db.user

Enter the BAM database user name.

bam.db.password

Enter the BAM database password.

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

111

Documentum repository connection parameters

Property

Description

bam.db.name

Enter the BAM database name.

bam.dataloader.input.file

The BAM Data Loader configuration file. This file is optional.


Examples:
../etc/sql/create-tablespace.xml
../etc/sql/Cleanup.xml
../etc/sql/Crebas.xml

To connect with the repository you can either enter the path to the dfc.properties file, or enter the
repository name, username, password, IP address, and port. The following Documentum repository
properties are entered in the data-loader.properties file:
Table B.13

Documentum repository connection parameters

Property

Description

bam.dfc.properties.path

Enter the path to the dfc. properties file. The dfc.properties file is
the preferred approach to upgrading with the Data Loader. When
a valid path is entered, the dfc.properties file is the method used
for connecting to the repository instead of connecting by way of
the properties listed below. If you choose not to enter a valid
path, then place a pound sign (#) at the beginning of the property
to comment it out.

bam.repository

Enter the Documentum repository name. Enter this property when


you are not using the dfc.properties file.

bam.repository.user

Enter the Documentum repository username. Enter this property


when you are not using the dfc.properties file.
Enter the Documentum repository password. Enter this property
when you are not using the dfc.properties file.

bam.repository.password
bam.repository.host

Enter the Documentum repository host name or IP address. Enter


this property when you are not using the dfc.properties file.

bam.repository.port

Enter the Documentum repository port. Enter this property when


you are not using the dfc.properties file.

Figure 4

Sample data-loader.properties template

The data-loader.properties file is shipped with the upgrade scripts made available with BAM. The
data-loader.properties file is formatted as a template that provides a list of each property, an example of
a valid value, and then a space for the user to enter the connection property. In the following figure DB
dialect is the first property listed. Within the commented (#) section is a list of valid values. Just below
the commented section is a space for the actual DB dialect to be entered. The DB dialect is entered by
substituting $C(BAM, DCTM_BAM_DB_DIALECT) with a valid value.
Note: For each property in the data-loader.properties file, the characters to the left of the equal sign
(=) must remain.

112

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Working with the data-loader.properties file

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

113

Appendix C
Externalizing BAM configuration files

This appendix contains the following:

Externalizing BAM configuration files

Externalizing BAM configuration files


The BAM server requires write access to its configuration files. Deploying the BAM
server on some application servers (for example, Oracle Weblogic and IBM WebSphere)
requires BAM configuration files to be externalized. Five configuration files are located in
.../bam-server.war/WEB-INF/classes/config/:
app-config.xml
common-config.xml
dfc-config.xml
env-config.xml
jdbc-config.xml
Externalizing BAM configuration files involves:
1. Creating an external configuration folder (for example, c:\bam\config\development).
2. Copying the BAM configuration files from .../bam-server.war/WEB-INF/classes/config/ to
c:\bam\config\development.
3. Specifying the location of the configuration files as described below.
The location of the BAM configuration files is specified either in a system property or by using a context
parameter within the BAM web application. The system property and context parameter name are both
bpm.resource.dir. The value of the system property is set in the application server startup script.
The value of the context parameter is set within .../bam-server.war/WEB-INF/web.xml. The
context-param element contains param-name, which is a constant string and param-value, which
is the path to the external folder. For example:
<context-param>
<param-name>bpm.resource.dir</param-name>
<param-value>c:\bam\config\development</param-value>
</context-param>

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

115

Appendix D
Security

This appendix contains the following:

Enabling HTTPS (SSL) for BAM

Configuring HTTPS on the application server

Configuring HTTPS on PRS

Downloading the certificate using Internet Explorer

Downloading the certificate using Mozilla Firefox

Configuring dashboards to communicate with BAM deployed on a secure server

Enabling HTTPS (SSL) for BAM


Communication between the BAM server, PRS, and Dashboard uses plain, unencrypted HTTP by
default. It is possible to deploy BAM so that it uses SSL HTTP Most application servers provide an
easy way to do this deployment. In order for client applications to work, it is not enough to point them
to the new address. A trust relationship based on authentication must be created between the client
computer and the application server. This relationship involves generating a certificate on the server
and registering this certificate on the client computer.

Configuring HTTPS on the application server


Refer to application server documentation for instructions on configuring security. Each application
server has a different way of configuring SSL.

Configuring HTTPS on PRS


On the client side, a browser requires no additional settings. When connecting to the application using
a web browser, the browser facilitates the creation of a trust. It typically accepts all certificates signed
by a recognized authority, and prompts the user to accept those certificates that are not recognized.
For PRS, an additional manual step is necessary. Install the certificate from the server in the
Java keystore on the client machine. The easiest approach is to connect with the web browser to
the application and to download the certificate to the client computer. In the following sections,
step-by-step procedures are available for both Internet Explorer and Mozilla Firefox. After the
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

117

Downloading the certificate using Internet Explorer

certificate is in the local path, open a command-prompt, change the directory to <PATH TO
PRS>\jre\bin and execute the following:
keytool -importcert -alias <ANY NAME> -file <PATH TO CERTIFICATE FILE>
-keystore ..\lib\security\cacerts

Downloading the certificate using Internet


Explorer
This section provides the procedure for downloading the certificate using Internet Explorer.
To download the certificate using Internet Explorer:
1. Browse to the URL of the BAM server.
2. If the Security Alert dialog appears, then the certificate is unrecognized. Click View Certificate.
The Certificate dialog appears.
3. If the Security Alert dialog does not appear, then the certificate is already trusted by the browser.
Double-click the yellow lock icon on the status bar at the bottom of the browser window. The
Certificate dialog appears.
Note: For Internet Explorer 7, the yellow lock icon appears to the right of the address bar at the
top of the browser window. After double-clicking it, you must click the View Certificates link.
4. On the Certificate dialog, select the Details tab and then click Copy to File. The Certificate
Export Wizard dialog appears.
5. On the Certificate Export Wizard dialog, click Next.
6. Accept the default of the certificate file format and click Next.
7. In the File name field, enter or choose a location in the file system to save the certificate.
8. Click Next.
Note: You should make a note of the location of the saved certificate and reference this location in
the keytool command outlined in Configuring HTTPS on PRS, page 117.

Downloading the certificate using Mozilla


Firefox
This section provides the procedure for downloading the certificate using Mozilla Firefox.
To download the certificate using Firefox:
1. Browse to the URL of the BAM server.
2. If the Secure Connection Failed dialog appears, then the certificate is unrecognized. Click Or
you can add an exception and then click Add Exception.
118

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Security

3. If the Secure Connection Failed dialog does not appear, then the browser trusts the certificate.
Double-click the yellow lock icon on the status bar at the bottom of the browser window. Then
proceed to step 5.
4. On the Add Security Exception dialog, click View. The Certificate Viewer dialog appears.
5. On the Certificate Viewer dialog, click the Details tab.
6. Then, click Export and save the file in the default format.
Note: Make a note of the location of the saved certificate and refer to this location in the keytool
command.

Configuring dashboards to communicate with


BAM deployed on a secure server
TaskSpace and the BAM server are installed on separate physical machines (servers) that are either
secure or not secure. Your deployment of BAM fits into one of four use cases:
1. If both TaskSpace and the BAM server are deployed on non-secure servers, then no manual
configuration is required.
2. If TaskSpace is deployed on a secure server and the BAM server is deployed on a non-secure
server, then no manual configuration is required.
3. If TaskSpace is deployed on a non-secure server and the BAM server is deployed on a secure
server, then manual configuration is required.
4. If both TaskSpace and the BAM server are deployed on secure servers, then manual configuration
is required.
Note: The following procedure is only required when the BAM server is deployed on a secure server
regardless of the security of the TaskSpace server.
This section includes a procedure for configuring dashboards to use an HTTPS protocol when
communicating with the BAM server. This procedure involves modifying an XML file within the
TaskSpace WAR file before deploying TaskSpace.
To configure dashboards to communicate with BAM deployed on a secure server:
1. Download the TaskSpace WAR file from the EMC Download Center.
2. Extract the taskspace.war.zip file.
3. Open the dashboardProperties.xml file located in taskspace.war\taskspace\config\dashboard.
4. Modify the value of the useSsl parameter to true.
<init-param>
<param-name>useSsl</param-name>
<param-value>true</param-value>
</init-param>

5. Save the changes.


6. Repackage the contents of the extracted WAR file into a new WAR file.
EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

119

Configuring dashboards to communicate with BAM deployed on a secure server

7. Deploy TaskSpace.

120

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

Index
B

BAM
configuring, 81
BAM administration
activate monitoring, 82
BAM server
activate, 82
connecting to, 81
installing on Apache Tomcat application
server, 39
installing on IBM WebSphere application
server, 55
installing on JBoss application server, 31
installing on Oracle application server, 65
installing on Sun application servers, 73
installing on the WebLogic application
server, 47

post-installation
guidelines, 28, 38, 45, 54, 63, 72, 79
preconfigured dashboard
installing, 87
Process Reporting Services
installing, 83

C
configure
BAM Host URL, 28, 38, 45, 54, 63, 72, 79
BAM Port, 28, 38, 45, 54, 63, 72, 79
configuring
BAM, 81

T
troubleshooting
BAM installation using installer, 29

U
unpacking and repacking
WAR files, 109
upgrading
BAM 6.5 SP1 to 6.5 SP2, 91
BAM 6.5 SP2 to 6.6, 93
BAM 6.5 to 6.5 SP1, 89
BAM 6.6 to 6.7, 95
using BAM installer, 25

W
D
database
preparing, 17
documentation conventions, 7

WAR files
unpacking and repacking, 109

I
installing
BAM server, 25
BAM server on Apache Tomcat
application server, 39
BAM server on IBM WebSphere
application server, 55
BAM server on JBoss application server, 31
BAM server on Oracle application server, 65
BAM server on Sun application servers, 73
preconfigured dashboard, 87
Process Reporting Services, 83

M
migrating
BAM 6.5 SP1 to 6.5 SP2, 91
BAM 6.5 SP2 to 6.6, 93
BAM 6.5 to 6.5 SP1, 89
BAM 6.6 to 6.7, 95
Monitoring
activate, 82

EMC Documentum Business Activity Monitor Version 6.7 Installation Guide

121

Das könnte Ihnen auch gefallen