PRPC5-4SP2 J2EE Install Guide Tomcat

PegaRULES Process Commander
Release V5.4 SP2
Installing on Tomcat Application Servers
June 26, 2008

© Copyright 2008
Pegasystems Inc., Cambridge, MA
All rights reserved.
This document and the software describe products and services of Pegasystems Inc. It may contain trade
secrets and proprietary information. This information should not be disclosed to third parties unless otherwise
provided for by a contract or business agreement with Pegasystems. This document and the software are
protected by federal copyright law, international laws, and/or applicable treaties.
This document is current as of the date of publication only. Changes in the document may be made from time
to time at the discretion of Pegasystems. This document remains the property of Pegasystems and must be
returned to it upon request. This document does not imply any commitment to offer or deliver the products or
services provided.
This document may include references to Pegasystems product features that have not been licensed by your
company. If you have questions about whether a particular capability is included in your installation, please
consult your Pegasystems service consultant.
Other brand or product names are trademarks of their respective holders.
This document is the property of:

Pegasystems Inc.
101 Main Street
Cambridge, MA 02142-1590
Phone: (617) 374-9600

Fax: (617) 374-9620
www.pega.com
PegaRULES Process Commander

Document: Installation Guide
Software Version: 5.4 SP2
Updated: June 26, 2008
Contents
Chapter 1: Introduction ................................................................................................................. 1

Process Commander Core Component Versions ................................................................ 4
Overview of the Installation Procedure ................................................................................. 5
Prerequisites ............................................................................................................................ 6
Supported Process Commander Platforms ................................................................... 6
Support During the Installation Process ............................................................................... 8
Check the Pega Developer Network for the Latest Information ................................... 8
A Note for PRPC 4.2 Users .............................................................................................. 9
Chapter 2: Preparing the Database ............................................................................................ 10

Database Prerequisites ......................................................................................................... 11
Creating a PRPC Database ................................................................................................... 11
Creating Access to the Database ......................................................................................... 12
User Permissions for the Microsoft SQL Database .................................................... 13
User Privileges for the Oracle Database ...................................................................... 13
User Privileges for the UDB Database.......................................................................... 14
Creating Tables in the Database .......................................................................................... 14
Chapter 3: Preparing the Application Server ............................................................................ 16

Verify the Java Environment ................................................................................................ 17
Configuring Database support on your Application Server .............................................. 17
Microsoft SQL Server..................................................................................................... 17
Oracle 9i or 10................................................................................................................. 18
UDB ................................................................................................................................. 19
Chapter 4: Deploying Process Commander-Tomcat ................................................................ 20

Installing Tomcat ................................................................................................................... 21
Configuring Tomcat Before Deploying PRPC ..................................................................... 21
Setting JAVA_HOME ...................................................................................................... 21
Setting JVM Memory Parameters.................................................................................. 22
Enable AWT to support PRPC Graphical Reports ....................................................... 24
Setting User ID and Password in Tomcat .................................................................... 25
Enabling DNS Lookup.................................................................................................... 26
Setting Localization Libraries ....................................................................................... 26
Deploying the PRPC WAR Files ........................................................................................... 28
Start Tomcat and Open the Tomcat Home page ......................................................... 28
iv Pegarules Process Commander Installation Guide V5.4 SP12
Installing the PegaRULES Rule Import Application (prdbutil) ................................... 28

Configure the Database Connection.................................................................................... 31
Add Database Connection Information to prconfig.xml ............................................. 31
Specify explicit temp directory in prconfig.xml ........................................................... 34
Configuring the Oracle 9i/10g Client, version 9.2.0.5 or higher, for Process
Commander .................................................................................................................... 35
Configuring UDB for Process Commander .................................................................. 36
Installing the PegaRULES Application (prweb.war) ........................................................... 39
Edit the prconfig.xml for prweb .................................................................................... 40
Installing the System Management and Online Help Applications ................................... 41
Assigning the PegaDiagnosticUser Role to your System Management Application Users
................................................................................................................................................ 42
Next Steps ....................................................................................................................... 42
Chapter 5: Installing Process Commander ............................................................................... 43

Complete Rulebase Utilities (prdbutil.war) Setup Steps .................................................... 44
Create a Systems Management Node........................................................................... 58
Next Steps .............................................................................................................................. 64
Refer to Administration and Security Guide ................................................................ 64
Integration Information .................................................................................................. 64
Chapter 1:
Introduction
This document describes how to install a new instance of PegaRULES Process
Commander 5.4 SP2. Upgrading an existing Process Commander installation is
described in other documents:
■ To upgrade a Process Commander 4.2 system to 5.4 SP2, your current

system must first be at 4.2 SP6. If your current system is earlier than 4.2
SP6, see the Upgrade Guide for 4.2 SP6 for instructions on moving to SP6.
■ To upgrade from 4.2 SP6 to 5.4 SP2, see the manual Upgrade Guide, V4.2
SP6 to V5.
■ For information about upgrading an existing Process Commander 5

installation (5.1, 5.1 SP1, 5.1 SP2, 5.2, 5.2 SP1, 5.3, 5.4, or 5.4 SP1) to 5.4
SP2, see the PegaRULES Process Commander Upgrade Guide 5.4 SP2,
released with Process Commander 5.4 SP2.
These documents and any updates to existing Process Commander

documentation are available on the Pega Developer Network (pdn.pega.com).
Please check this site for the latest installation and configuration information.
To create a new installation of Process Commander 5.4 SP2, you perform four
basic procedures:
1. Create a blank database on your database server and apply the Process
Commander 5.4 SP2 schema.
2 PegaRULES Process Commander Installation Guide v5.4 SP12
2. Configure your application server and deploy the Process Commander

application components on your application server.
3. Load the Process Commander application rulesets to the database.
4. Perform initial configuration of the Process Commander system.
You perform the first two steps with the database and application server
administrator tools, respectively. You use the Process Commander Database
Utilities application (prdbutil) to upload and install the application files, and to set
up the initial configuration of your Process Commander system.
To set up a Process Commander system, you deploy four software components
in your application server:
Process Commander Description

Component
prdbutil.war PegaRULES Process Commander Database Utilities – provides a
checklist and steps for the initial configuration and deployment of
Process Commander and utilities to load the Process Commander
data objects.
prweb.war or The Process Commander core application.
prpc_j2ee14.ear All Tomcat installations use prweb.war.
(See Process Commander Core Component Versions below.)
prhelp.war The online help system for the Process Commander application user
interface.
prsysmgmt.war A JMX (Java Management Extensions) client that allows
administrators to monitor multiple Process Commander nodes from a
single location.
The deployment of a basic installation instance is shown in the diagram below:

3
Process Commander Core Component Versions

The PRPC core application is packaged in five different versions to support the
deployment of PRPC into different J2EE environments. The following table
summarizes all the packages provided and their use:
Type of deployment PRPC package to use

All Tomcat deployments prweb.war
All new deployments on WebSphere 6.x, WebLogic 9.x or 10, prweb.war or
Oracle Application Server 10g Release, or JBoss 4.2.3 prpc_j2ee14.ear
Note: The legacy packages listed below are provided only for existing customers to
support backward compatibility. Contact customer support before deploying.
All new deployments on WebSphere 5.x or WebLogic 8.x prweb.war or
prpc_j2ee13.ear
Existing deployments on WebSphere 6.x or WebLogic 9.x that prweb.war or

used prweb.ear prweb_j2ee14.ear
Existing deployments on WebSphere 5.x or WebLogic 8.x that prweb.war or
used prweb.ear prweb_j2ee13.ear
Tomcat users should install the WAR in all cases.

If you have any questions regarding the correct package to deploy, contact Pega
Support.
5
Overview of the Installation Procedure

The following outline details the steps in the 5.3 installation process:
1. Prepare the Database server

– Create a database with a PRPC user and password
– Install the PRPC schema appropriate for your database vendor
2. Prepare the application server

– Configure the server environment
– Verify the Java environment
– Create and verify the database connection.
– Verify the PRPC Temporary directory
3. Deploy the PRPC components.
4. Install the Process Commander rulesets

– Start the Process Commander Database Utilities application
(prdbutil.war)
– Upload the application files from the Process Commander distribution to
your application server
– Install the Process Commander application instances to the database
5. Configure Your PRPC system

– Optionally configure a Lucene search engine to support Rule and Work
Object searches in Process Commander
– Configure the Help and System Management applications
– Setup an initial user organization
The procedures to complete these steps are described in the rest of this
document.
Prerequisites
The prerequisites for installing Process Commander are:
■ An application server host computer with adequate memory and disk space
for the installation.
– Process Commander requires a minimum of one GB of free memory.
This is in addition to any memory allocated for the operating system or
other applications on the server. The memory required for your system
may need to be higher, depending on the number of users and your
specific configuration.
■ A working installation of the application server.
■ Configured relational database available for Process Commander use, and

support in your organization for the installation and configuration of relational
databases.
The database requires a minimum of 500 MB for the user tablespace. The
space required for your system may need to be higher, depending on your
specific configuration.
Note: If you have difficulty installing any of the third-party software required
by Process Commander, contact the other software vendor to resolve the
issues before installing Process Commander.
Supported Process Commander Platforms

Because Process Commander is developed to industry standards — Java and
J2EE technologies, J2EE compliant application servers, SQL databases, web
browsers, XML, and HTML— a Process Commander system can be successfully
deployed on a wide range of hardware and software platform combinations.
However, careful selection of your platform components can make your
installation and deployment of Process Commander easier.
To determine the right platform components for your Process Commander
deployment:
1. Review the current Platform Support Guide, which is available on the Pega
Developer Network (PDN) or from your Pega account executive. This
document lists the recommended software components needed to support
Process Commander, and any special requirements or known issues with
particular vendors or versions.
2. Review your site’s deployment requirements with your IT representatives.

7
3. Consult with your Pegasystems representative about your installation

plans. Pegasystems’ prior experience with various platforms and
deployment architectures can help your installation go smoothly.
For additional information see the Platform Support Guide, which is available as
a PDF file on the Pega Developer Network (PDN), located at
http://pdn.pega.com.
Support During the Installation Process

During the Installation process, you may need access to team members who can
perform the following roles:
■ A system administrator to provide network and computing resources.
You will need a system administrator with knowledge of your IT infrastructure

and appropriate access to it, for example, usernames and passwords with
administrative privileges.
■ A database administrator to create and configure the Process Commander

database system.
You will need an experienced DBA with appropriate passwords and

privileges to create, access, and write to the database you will use to support
Process Commander.
■ An application server administrator to prepare the application server to

provide the runtime environment, connections and resources needed by the
Process Commander applications.
This resource must have administrative access to the application server

system and appropriate user names and passwords for the database system
so he or she can establish the JDBC connection from the application server
to the database.
■ A Process Commander administrator to deploy the Process Commander

applications in the application server and complete the initial configuration of
the Process Commander system.
You will need an administrator/deployer who has knowledge of the

configuration requirements for your Process Commander implementation.
This is usually the same person who has prepared the application server.
Check the Pega Developer Network for the Latest Information

Before beginning your installation procedure, check the Pega Developer Network
(PDN), located at http://pdn.pega.com, for the latest information. In addition to
the Platform Support Guide described in the previous section, also look on the
PRPC Documentation page for updated versions of this document and the
Upgrade guides.
Deployment information and updates

Check the Deployment page on the Pega Developer Network for information,
updates, and platform bulletins on deploying Process Commander.
9
This page also includes links to WebEx recordings demonstrating the

deployment of the Process Commander software components and the use of the
Process Commander Database Utilities application.
Visit http://pdn.pega.com and click “PRPC Deployment.”
Pegasystems Documentation
The latest Process Commander documentation is available on the
Documentation page of the Pega Developer Network.
Visit http://pdn.pega.com and click “PRPC Documentation.”
Pegasystems Training
A range of Pegasystems course offerings are available to increase the
effectiveness of your deployment and development team members. For more
information, visit http://www.pega.com/Training
Check Knowledge Base Platform Bulletins
You should also consult the following Platform Bulletins to learn about any known
issues that might affect the PRPC installation on your platform:
Title PRPC KB #
Sun JVM Issues 21247
IBM JVM Issues 21248
WebLogic Issues 21352

WebSphere Issues 21353
Oracle Issues 21864
You can search for these bulletins on the PDN using the KB number.
A Note for PRPC 4.2 Users

This installation procedure differs from earlier installation procedures in
significant ways. Please review the instructions carefully.
In particular, be sure to create and configure a temporary directory that Process
Commander can use to store static data. See the section “Setting the Explicit
Temporary Directory” in the chapter that describes deployment with your
application server.
Chapter 2:
Preparing the Database Server
To prepare your database server to use with Process Commander, you must
complete the following tasks:
■ Create a blank database.
■ Create an appropriate user that Process Commander can use to access the
database.
■ Run Process Commander SQL scripts to create PRPC data objects in the
database.
Each of these steps is described in the following sections.

11
Database Prerequisites
Process Commander requires a working installation of one of the supported
databases before installation Process Commander.
■ For 5.4 SP2 the supported database versions are the following:
– DB2 UDB v8.1, v8.2, v9.1
– DB2 for zOS v8.1, 9.1
– Oracle 10g
– SQL Server 2000, 2005
For additional information, see the Platform Support Guide, which is available
as a PDF file on the Pega Developer Network (PDN). Go to
http://pdn.pega.com and click Product Documentation.
■ Install and configure the relational database according to vendor directions.

This database may reside on the same server as the Process Commander
software, or it may be on a different server.
Creating a PRPC Database

Create a database with a minimum of 500 MB for the user tablespace. The
space required for your system may need to be higher, depending on your use of
PRPC.
Be sure to record:
■ Database server name
■ Database port number
The Process Commander system requires this information to access this

database.
Additional UDB Requirements

When using UDB:
■ Process Commander requires a buffer pool and temporary tablespace with a

minimum page size of 16K for each tablespace that contains Process
Commander tables. By default, the UDB database create process creates a
bufferpool and temporary tablespace with only a 4K page size.
If your use exceeds the page size, PRPC generates a PRRuntimeException

error. Depending on your use, you might need to make the buffer size
greater than 16K.
■ Process Commander requires a C++ compiler on the UDB database

machine to support stored procedures.
Creating Access to the Database

Create a user for this database with full read and write permissions. At a
minimum this “base” Process Commander user must have appropriate read and
write permissions to be able to run SQL scripts on the database. In addition, a
small number of Process Commander functions require permission to run
CREATE_TABLE and ALTER_TABLE operations. You can assign permissions
that include these operations to the base user, or you can create a second Admin
DB user with these extended permissions which Process Commander uses only
for these special functions. For details, see “Creating Base and Admin Database
Users,” below.
When you configure data access in your application server, you must provide the
user name and password for the user or users you have created to access the
Process Commander database. Be sure to record this information and have it
available when configuring the application server. For more information, see
“Configure the Database Connection” on 31.
Creating Base and Admin Database Users

If possible, it is best to create a single Process Commander user with the full
permissions. If you want to restrict users’ access to the Process Commander
database, you can create two users:
■ A “base” user with only read and write permissions.
■ An Admin user with full access including permission for CREATE_TABLE

and ALTER_TABLE operations.
To implement two users, you configure access to the database in your

application server by creating two data sources:
■ One datasource referencing the JNDI location jdbc/PegaRULES that

specifies the username and password for the base DB user. This user must
have at least read and write permissions for the database.
■ A second datasource referencing the JNDI location jdbc/AdminPegaRULES

specifying the username and password for the DB Admin user. This user
must have the full system permissions for the database.
For information about specifying these data sources, see “Configure the
Database Connection” on 31.
13
How Process Commander Uses the two Database Accounts
If you configure a second datasource for the Admin user, Process Commander
uses that user when performing a small number of functions that require altering
the database, specifically:
■ Using the Database Schema Management tool (Tools > Database > Modify
Database Schema.)
■ Creating any new Circumstance Definition rule or defining a single

circumstance on a rule. The extended permissions are needed to support
reporting on circumstanced properties. (On the Pega Developer Network,
see PRKB-25173: How to create a rule with multiple circumstance
properties.)
■ Exposing embedded properties for selection and reporting. (On the Pega
Developer Network, see PRKB-25278: How to create Declarative indexes for
embedded properties.)
For all other functions, Process Commander uses the base DB user which only
requires read and write permissions.
If you do not provide ALTER TABLE and CREATE TABLE permissions to any
user, Process Commander generates a warning when you use any of these
features. The warning includes SQL script that you can provide to your DBA to
manually make the necessary database changes.
Follow the guidelines for the appropriate database in the following sections
User Permissions for the Microsoft SQL Database

Set the user account for the “PegaRULES User” with a public and db_owner
role with all corresponding System Permissions granted.
User Privileges for the Oracle Database

Set the user account for the “PegaRULES User” with the default RESOURCE
and CONNECT roles with all corresponding system privileges granted. In
particular, be sure that the user has the Create View system privilege.
Note: On the Oracle 10g HTML-based Enterprise Manager console there are
separate tabs for setting the user’s roles and system privileges. When editing
the properties for the Pega user, be sure to go to the Roles tab to set the
RESOURCE and CONNECT roles, and then to the System Privileges tab to
set the Create View system privilege.
Important: Do not grant DBA access to the user, as this may cause
problems with the installation.
User Privileges for the UDB Database

Create a user account for a PegaRules user according to the IBM instructions.
Creating Tables in the Database

To create the Process Commander tables in the database, the database
administrator (DBA) must run a SQL script to create the appropriate tables in the
relational database into which Process Commander will load its rules. Process
Commander V5.4 SP2 includes SQL scripts for each supported database.
Scripts are available for:
• db2 z/OS
• mssql
• oracle (oracledate)
• udb
Each of databases has a folder located in the Distribution Image under the
\schema\DDL directory. Choose the appropriate folder for your database and
find the <database>_install0504.sql file.
Example:
schema\DDL\oracledate\oracledate_install0504.sql
The DBA should review this script and customize it (if necessary). When
satisfied with the script, the DBA can run it to create the tables. The default
scripts create an ASCII database. Modify the scripts if you require Unicode.
Note: For MS-SQL installations only, the following message may appear:
Warning: The table 'pr4_rule' has been created but its maximum row size
(8506) exceeds the maximum number of bytes per row (8060). INSERT or
UPDATE of a row in this table will fail if the resulting row length exceeds 8060
bytes.
You may ignore this message.
This warning message relates to a known limitation of Microsoft SQL Server.
Other Process Commander SQL scripts

15
The directory for each database also includes SQL scripts to drop and truncate
the Process Commander schema tables:
<database>_drop.sql
<database>_truncate.sql
For example:
mssql_drop.sql
mssql_truncate.sql
Your database administrator may find these scripts useful when maintaining the
Process Commander database.
In addition, this directory contains the following upgrade scripts that modify an
existing PRPC database to conform to the schema for a later release:
– oracledate_upgrade_alters_0402SP6to0504.sql
– oracledate_upgrade_alters_0501GAto0504.sql
– oracledate_upgrade_alters_0502to0504.sql
– oracledate_upgrade_alters_0503to0504.sql
– oracledate_upgrade_drops_0402SP6to0504.sql
– oracledate_upgrade_drops_0501GAto0504.sql
– oracledate_upgrade_drops_0502to0504.sql
– oracledate_upgrade_drops_0503to0504.sql
The scripts labeled “alters” add columns to the current database for a release to
make it conform to the database for the new release. No data is changed. The
scripts labeled “drops” drop objects from the current database that are no longer
present in the new release’s schema. Your application’s data may be deleted by
this script.
For more information, see the appropriate upgrade guide.
Important: Your database administrator should review the commands in

these SQL scripts to understand the changes they will make in your PRPC
database before they are run.
Contact Customer Support if you have questions about the use of these
scripts.
Chapter 3:
Preparing the Application Server
This chapter describes tasks you must complete on your application server
before beginning to deploy the PRPC application:
■ Verify the Java Environment
■ Configuring Database support on your Application Server
Detailed Procedures for deploying the PRPC application components on Tomcat

are given in Chapter 4, Deploying Process Commander-Tomcat.
17
Verify the Java Environment

Confirm that the Java JDK environment used by your application server is Java
JDK 1.4.2 or higher.
Refer to the Platform Support Guide, available as a PDF file on the Pega
Developer Network (PDN) located at http://pdn.pega.com, for specific
recommendations for your platform.
Important: During installation, Process Commander requires access to the

directory specified by the java.io.tmpdir setting in the JVM. Confirm that there
is write access to this directory before installing Process Commander.
Be sure your application server is configured to use an appropriate JDK. The

default Java environment for your application server may not be one of the
recommended JDKs for Process Commander.
Configuring Database support on your Application Server

In order to support JDBC connections between your application server and the
Process Commander, you must install the appropriate database client software
and JDBC drivers on your application server as recommended by your database
vendor.
Microsoft SQL Server

Download the latest drivers from the Microsoft website.
■ For Microsoft SQL Server 2005, be sure that the driver file, sqljdbc.jar is
installed correctly.
■ For Microsoft SQL Server 2000, the following files are required:
– msbase.jar
– msutil.jar
– mssqlserver.jar
These drivers for Microsoft SQL Server JDBC are Type 4.

For Tomcat, use the Microsoft installation procedure to install the drivers into the
<Tomcat_HOME>/common/lib directory for Tomcat 5 installations, or
<Tomcat_HOME> /lib for Tomcat 6 installations.
Example:
e:/TC-6.0.14/lib
Oracle 9i or 10
Note: For Oracle 9i, the JDBC driver 9.2.0.4 (for the client) is not supported.
Supported versions include: 9.2.0.1, 9.2.0.2, 9.2.0.3, and 9.2.0.5.
Oracle Installation Edits

For Process Commander to work with the application server using Oracle, follow
all Oracle instructions for installing the client software and the JDBC drivers.
Install the JDBC driver ojdbc14.jar with the Oracle Client software in the /jdbc/lib
directory:
oracle-home/jdbc/lib
Example:
c:\oracle\ora92\jdbc\lib
Edit as follows for Solaris:
■ Set ORACLE_HOME and LD_LIBRARY_PATH environment variables.
■ Add $ORACLE_HOME/lib32 to the LD_LIBRARY_PATH before the

reference to the standard $ORACLE_HOME/lib directory (as Process
Commander uses 32-bit libraries).
Edit as follows for AIX:
■ Set ORACLE_HOME and LIBPATH environment variables.
■ Add $ORACLE_HOME/lib32 to the LIBPATH before the reference to the

standard $ORACLE_HOME/lib directory (as Process Commander uses
32-bit libraries).
For the Windows environment, the necessary environment variables (such as

ORACLE_HOME and Path) are set automatically by the Oracle installation
program.
Be sure the application server is configured to load this JDBC driver in the
classpath.
Validating the Oracle Connection

Login into SQL*Plus to validate the Oracle connection. For example, enter the
following command on the server:
19
userid/password@SID
Example:
$sqlplus oratest/oratest@oratest.rpega.com
In this example, oratest is the userid, oratest is the password, and

oratest.rpega.com is the SID. This should return Oracle system information and
the Connected to: message.
SQL*Plus: Release 10.1.0.2.0 - Production on Mon Nov 27 11:08:28 2006

Copyright (c) 1982, 2004 Oracle Corporation. All rights reserved.
Connected to:
Oracle Database 10g Enterprise Edition Release 10.1.0.2.0 – Production
With the Partitioning, OLAP, and Data Mining options
SQL>
If problems logging in occur (that is, the above messages do not appear), resolve
these issues first before loading Process Commander.
UDB
For Process Commander to work with a web application server using DB2 UDB,
follow the IBM instructions for installing the client software and the JDBC drivers.
For DB2, the JDBC driver db2jcc.jar file is required.
This JDBC driver is Type 4.

For Tomcat, use the DB2 installation procedure to install the driver into the
<Tomcat_HOME>/common/lib directory for Tomcat 5 installations, or
<Tomcat_HOME> /lib for Tomcat 6 installations.
Example:
e:/TC-6.0.14/lib
Notes: In UDB, Process Commander requires a 16K-page buffer pool and

tablespace for each tablespace that contains Process Commander tables.
Process Commander uses stored procedures. It therefore requires a C++

compiler on the database machine.
Chapter 4:
Deploying Process Commander-
Tomcat
This chapter describes the procedures for deploying PRPC on a Tomcat server.
To complete this deployment you perform the following tasks:
The following is a checklist for deploying the WAR file in Tomcat:
1. Predeployment configuration of Tomcat for Process Commander

– Setting JAVA_HOME
– Setting JVM Memory Parameters
– Enable AWT to support PRPC Graphical Reports
– Setting User ID and Password in Tomcat
– Enabling DNS Lookup
– Setting Localization Libraries
2. Deploying the WAR file
3. After Deploying the WAR file – Process Commander customization

– Deleting the extra WAR file
21
Installing Tomcat
On UNIX or Windows platforms, you can install Tomcat on your server machine
by downloading the Core Binary Distribution as a zip file from the Tomcat site
(http://tomcat.apache.org) and unzipping the distribution into a top-level directory
on your server machine.
Windows users can also install Tomcat using the Windows Executable
installation option. However, this installer automatically installs Tomcat as a
Windows Service no matter which setting is selected in the installation dialog. If
you are running Tomcat as a Windows service pay particular attention to the
requirements for setting the JVM memory options as described Setting JVM
Memory Parameters, on page 22. If you install on Windows using the setup.exe
file, the Administration Tool is installed automatically.
Note: For additional information on console-based deployment in Tomcat, as

well as information on advanced options and settings, consult the Tomcat
documentation (http://jakarta.apache.org/tomcat/tomcat-5.5-doc/index.html).
Configuring Tomcat Before Deploying PRPC

Make the following changes to configure Tomcat for the Process Commander
installation:
■ Setting JAVA_HOME
■ Setting JVM Memory Parameters
■ Enable AWT to support PRPC Graphical Reports
■ Setting User ID and Password in Tomcat
■ Enabling DNS Lookup
■ Setting Localization Libraries
Note: After entering these changes into the Tomcat system, stop and restart
the Tomcat server.
For information on customizing Tomcat, see the Process Commander Support

Knowledgebase. Tomcat documents will also be installed in the Tomcat
installation, under the TomcatInstallDirectory\webapps\tomcat-docs subdirectory.
Setting JAVA_HOME
Confirm that the application server has a JAVA_HOME environment variable set
in your environment; it must be configured to point to the top level of your current
Java installation. If this variable is not set properly, the following error results
when the application server attempts to start:
“Cannot find the file ‘-Xms128m’ (or one of its components). Make sure the path
and filename are correct and that all required libraries are available.”
To check the JAVA_HOME environment variable on Windows, select Start >

Settings > Control Panel > System > Advanced > System Variables.
Setting JVM Memory Parameters

You must set the JVM memory options to increase the amount of system
memory allocated to the server running PRPC. If the server does not have
enough memory allocated to run Process Commander, the system may hang
without an error message. The following minimum values are required:
■ Initial Java heap size (Xms): 512M
■ Maximum heap size (Xmx): 768M
If your application server is using the Sun JVM, add the PermSize and
MaxPermSize settings as well:
■ PermSize: 64MB
■ MaxPermSize: 256MB
The method you use to set the memory parameters for the JVM depends on the
way you installed Tomcat:
■ If you installed Tomcat using the .zip file, on Windows or UNIX, and are not
running Tomcat as a service on Windows, create a setenv .bat or .sh file
containing the settings. See Creating the setenv File below.
■ If you installed Tomcat on Windows using the .exe installation program,

Tomcat is automatically installed as a service. You must set the JVM options
for the Tomcat service using a command entered at a command-prompt
window. See “Setting the Memory Parameters for the Windows Service” on
page 23.
■ If you install Tomcat on Windows using the .zip file and then install it as a
service using the service.bat file distributed with .zip distribution, you must
include the memory settings in the service.bat file before running it. See
Setting the Memory Parameters in the service.bat File on page 23.
Creating the setenv File

Use this method to set the memory parameters on UNIX systems, or if you do
not run Tomcat as service on Windows.
23
Create a startup script, setenv.bat for Windows or setenv.sh for UNIX, in the
TomcatInstallDirectory/bin directory. These scripts do not exist in a default
installation.
If Tomcat is installed on a Windows machine, create the setenv.bat file with the
following information:
rem Change -Xmx value based on available physical memory

set JAVA_OPTS=-Xms512m –Xmx768m –XX:PermSize=64m –XX:MaxPermSize=256m
rem End of lines added by PegaRULES Installation Process
For a UNIX server, create a setenv.sh file:
# Change -Xmx value based on available physical memory

JAVA_OPTS=”-Xms512m –Xmx768m –XX:PermSize=64m –XX:MaxPermSize=256m”
# End of lines added by PegaRULES Installation Process
Note: The JAVA_OPTS settings should all be on one line.
Caution: Do not start Tomcat from the Windows START menu. This uses a
Tomcat bootstrap mechanism that alters the CLASSPATH and bypasses the
setenv.bat settings. This causes startup failures and memory errors. After
you save the setenv.bat file, always start Tomcat from a command line using
the startup.bat file.
Setting the Memory Parameters for the Windows Service
If you used the Windows installation program, you must set the JVM options for
the Tomcat service using the following command.
Open a command prompt window and change directories to the bin directory of
your Tomcat installation. At the command prompt, enter the following command:
.\tomcat5.exe //US//Tomcat5 ++JvmOptions=-Xms512m;-Xmx768m
or
.\tomcat6.exe //US//Tomcat6 ++JvmOptions=-Xms512m;-Xmx768m

This command permanently sets the JVM options for the Tomcat service. These
memory settings will be used when you start the Tomcat service.
Setting the Memory Parameters in the service.bat File

The .zip distribution of Tomcat includes a file, service.bat that you can use to
install and uninstall Tomcat as a service on Windows. You can find this file in the
bin directory of your Tomcat installation. If you use this file to install Tomcat as a
service, include the memory parameters, as described above, as JVM options in
the file. The file contains instructions and examples for setting JVM options.
About the JVM Memory Parameters
The following parameters must be adjusted in the Tomcat startup for system
memory:
■ Initial Java heap size (Xms)
■ Maximum heap size (Xmx)
■ PermSize
■ MaxPermSize
Pegasystems recommends setting the initial Java heap size to 512m.
For the maximum heap size, Pegasystems recommends running with 768m
Although there is no specific equation to determine heap size from usage, this
setting may need to be moved higher as more users work with the system,
especially if the system supports:
■ A large number of users
■ A large number of agents
■ Rules Moves with large rulesets
The PermSize and MaxPermSize settings change the size in the portion of the
heap where the JVM stores dynamic class files (the permanent generation area),
and affect garbage collection in that area. These settings are only needed if
Tomcat is installed on Sun Solaris. For the PermSize setting, the default is 8MB
and should be set to 64MB. For the MaxPermSize setting, the default is 64MB;
and should be set to 256MB to prevent out-of-memory errors.
Note: These JAVA_OPTS settings are minimum amounts only. To begin

using Process Commander; your settings may need to be higher, based on
your server hardware and the number of other applications on the server.
Enable AWT to support PRPC Graphical Reports

You must add a “headless” AWT setting to the JAVA options in the setenv.bat
(Windows) or the setenv.sh (UNIX) file that are passed to Java at startup to allow
the system to render graphics. PRPC requires this setting in order to display
25
graphical reports. For more information, see Creating the setenv File on page
22.
Add or modify the JAVA_OPTS setting in the setenv.bat (Windows) or the

setenv.sh (UNIX) file to include:
–Djava.awt.headless=true
For example, your settings may look similar to the following:
# Change -Xmx value based on available physical memory

JAVA_OPTS=”-Xms256m –Xmx768m –XX:PermSize=64m
–XX:MaxPermSize=160m -Djava.awt.headless=true”
Setting User ID and Password in Tomcat

If you installed Tomcat on UNIX, or on Windows using the .zip distribution, you
must enter user ID and password information into the tomcat-users.xml file in
the TomcatInstallDirectory/conf directory. Windows users that use the Tomcat
setup.exe file to install should also verify the user name and password created in
this file.
This file sets some default roles for users logging onto the Tomcat server:
<?xml version='1.0' encoding='utf-8'?>

<tomcat-users>
<role rolename="tomcat"/>
<role rolename="role1"/>
<user username="tomcat" password="tomcat" roles="tomcat"/>
<user username="role1" password="tomcat" roles="role1"/>
<user username="both" password="tomcat" roles="tomcat,role1"/>
</tomcat-users>
Add an administrator and manager role, as follows:
<?xml version='1.0' encoding='utf-8'?>

<tomcat-users>
<role rolename="tomcat"/>
<role rolename="role1"/>
<role rolename="manager"/>
<role rolename="admin"/>
<user username="tomcat" password="tomcat" roles="tomcat"/>
<user username="role1" password="tomcat" roles="role1"/>
<user username="both" password="tomcat" roles="tomcat,role1"/>
<user username="admin" password="admin" roles="admin,manager"/>
</tomcat-users>
For more information on user configuration in Tomcat, see the Tomcat’s online
documentation.
Enabling DNS Lookup

The Tracer in Process Commander requires that DNS lookup be enabled in order
to display the name of the client host, rather than its IP address. To enable DNS
lookup, set enableLookups="true". This setting is found in the server.xml file,
located in the conf directory. An example is shown below.
<Connector enableLookups="true" />
Setting Localization Libraries

Note: The following information is for MS-SQL installation only.
The setclasspath files are located in the TomcatInstallDirectory/bin directory. If

the customer database uses nonstandard character encoding (for
internationalization or other purposes), it is necessary to reference the Tomcat
localization libraries in the classpath.
The localization library settings differ depending upon the version of Java used:
■ Java 1.4.x: charsets.jar
Choose the appropriate .jar file for the Java version used, and edit the set
standard CLASSPATH section of the setclasspath file to include this .jar file.
Windows server – setclasspath.bat:
Original file:
rem Set standard CLASSPATH

rem Note that there are no quotes as we do not want to introduce random
rem quotes into the CLASSPATH
set CLASSPATH=%JAVA_HOME%\lib\tools.jar
With the addition:
rem Set standard CLASSPATH

rem Note that there are no quotes as we do not want to introduce random
rem quotes into the CLASSPATH
set
CLASSPATH=%JAVA_HOME%\lib\tools.jar;%JAVA_HOME%\jre\lib\charsets.jar
27
UNIX server – setclasspath.sh:
Original file:
Set standard CLASSPATH

CLASSPATH="$JAVA_HOME"/lib/tools.jar
#
With addition:
Set standard CLASSPATH

CLASSPATH="$JAVA_HOME"/lib/tools.jar:”$JAVA_HOME”/jre/lib/charsets.jar
#
Note: Be sure to install the appropriate JDBC drivers, as described in

Configuring Database support on your Application Server on page 17.
Deploying the PRPC WAR Files
Start Tomcat and Open the Tomcat Home page

Start Tomcat and open the Tomcat home page in a web browser by entering the
following URL:
http://localhost:8080
Installing the PegaRULES Rule Import Application (prdbutil)

1. From the Tomcat home page, click on the Tomcat Manager link. At the
login page, enter the user credentials you defined earlier in the tomcat-
users.xml.
29
2. Scroll down to the Deploy section and locate the WAR file to deploy
section.
3. In the section WAR file to deploy, click the Browse button to navigate to the
location of the prdbutil.war file and select it.
4. When the prdbutil.war file is displayed in the Select WAR file to upload
field, click the Deploy button to automatically install the application. This
will place the application into the
\<tomcat_install_root>\webapps\prdbutil directory and the application

will appear in the list of deployed applications.
Note: The name of your WAR file determines what Tomcat will use for the
context root value for the application.
5. When the application has been deployed, shut down Tomcat, and then
delete the prdbutil.war file from the \<tomcat_install_root>\webapps\
directory.
Tomcat uploads the WAR file to the webapps directory as part of the
deployment process. If you do not remove the WAR file after deployment,
Tomcat redeploys the application each time the server is restarted.
31
Configure the Database Connection

Update the PegaRULES configuration file (prconfig.xml) to include your
database connection information, as described in the next section. This file is
located under the contextroot directory for the application in the \WEB-
INF\classes subdirectory, for example C:\tomcat-
5.5.16\webapps\prdbutil\WEB-INF\classes.
For Oracle installations you will also need to create an oracle.conf file and add an
additional line to the prconfig.xml file. See “Configuring the Oracle 9i/10g Client,
version 9.2.0.5 or higher, for Process Commander” below.
For UDB installations, you will need to create a udb.conf file specifying additional
properties needed for the database connection, and add an additional line to the
prconfig.xml file referencing the file. See “Configuring UDB for Process
Commander” below.
Add Database Connection Information to prconfig.xml
1. Open the prconfig.xml file for editing.
2. Comment out the JNDI datasource entry:

– Near the top of the file, find the default datasource entry:
<env name="database/databases/PegaRULES/dataSource"
value="java:comp/env/jdbc/PegaRULES"/>
– Add comment tags, , around the element:

3. Uncomment the Pega database connection sample:

– The prconfig.xml file also contains an example database connection
commented out:

– Uncomment these lines by deleting the comment markers 
4. In the element “database/drivers,” change the value to reference the

appropriate database driver:
– Oracle 9i/10g: oracle.jdbc.OracleDriver
– IBM DB/2 Type 4: com.ibm.db2.jcc.DB2Driver
– SQL Server 2005: com.microsoft.sqlserver.jdbc.SQLServerDriver
– SQL Server 2000: com.microsoft.jdbc.sqlserver.SQLServerDriver
5. In the element "database/databases/PegaRULES/url", change the value to

the URL for your database server:
– Oracle 9i/10g (Native OCI Client):
jdbc:oracle:oci:@your_tns_name
– Oracle 9i/10g (Thin Client):
jdbc:oracle:thin:@myServer:1521:myDatabase
– DB/2 (Universal Driver):
jdbc:db2://serverName:port/dbName
– SQL Server 2005
jdbc:sqlserver://<your_sql_server_host>:1433;SendStringParametersAsUnic
ode=false;SelectMethod=cursor;ProgramName=${NodeName}:${SystemName}.${C
onnectionID}
– SQL Server 2000 (Type 4):
jdbc:microsoft:sqlserver://<your_sql_server_host>:1433;SendStringParametersAs
Unicode=false;SelectMethod=cursor;ProgramName=${NodeName}:${SystemName}.${Connec
tionID}
Specifically, change the bolded information in the example below to specify

your database:
value="jdbc:microsoft:sqlserver://localhost:1433;SelectMethod=cursor;SendStringP
arametersAsUnicode=false;ProgramName=PR ${SystemName}@${NodeName} ${DBName}
6. In the username and password elements, change the values bolded in the
following example to the user name and password you created for the
PRPC user on your database.
33
<env name="database/databases/PegaRULES/userName" value="username" />
<env name="database/databases/PegaRULES/password" value="password" />
7. Save prconfig.xml, but leave it open to complete the next procedure.
Optional: Create a reference for an Admin DB user

Complete this procedure to create a second DB user for Process Commander
with extended privileges. Three features in Process Commander require the
Process Commander user to have CREATE_TABLE and ALTER_TABLE
permissions on the Pegasystems database. If you do not want to give those
permissions to the Process Commander base user, you can give those
permissions only to an Admin user. See “Creating Access to the Database” on
page 12.
Complete the following steps to create a second datasource for a Process
Commander Admin user.
1. Make a copy of the data definition you created above for the Process
Commander base user
2. In the element "database/databases/PegaRULES/url", change PegaRULES

to AdminPegaRULES:
<env name="database/databases/AdminPegaRULES/url"
3. In the username and password elements, change PegaRULES to

AdminPegaRULES and provide the username and password for the Admin
DB user:
<env name="database/databases/AdminPegaRULES/userName" value="admin-

username" />
<env name="database/databases/AdminPegaRULES/password" value="admin-

password" />
This user must be configured on the database with full access permissions,
including CREATE_TABLE and ALTER_TABLE.
You finished data definition should look similar to the following:
value="com.microsoft.jdbc.sqlserver.SQLServerDriver;com.mckoi.JDBCDriver;oracle.
jdbc.OracleDriver" />
<env name="database/databases/AdminPegaRULES/url"
<env name="database/databases/AdminPegaRULES/userName"
value="admin_username" />
<env name="database/databases/AdminPegaRULES/password"
value="admin_password" />
4. Save prconfig.xml, but leave it open to complete the next procedure.
Specify explicit temp directory in prconfig.xml

While prconfig.xml is open, also create a reference to an explicit temporary
directory dedicated to Process Commander.
Note: Process Commander uses this directory as a staging directory for

archive imports, as storage for Index and other static content, and for
temporary storage. It is important to define a temp directory for Process
Commander separate from your system or application server temporary
directory.
1. In prconfig.xml, find the env element for the temporary directory:
<env name="Initialization/explicitTempDir" value="$(pega.tmpdir)" />
This is usually the fourth env element near the top of the file.
2. Replace $(pega.tmpdir) with the complete path to a directory that Process

Commander can use for static content and other temporary storage, for
example:
<env name="Initialization/explicitTempDir" value="/temp/Pega_temp" />
Note: Make sure that the Process Commander user on your system has
the appropriate permissions, including write access, to use this directory.
In particular, if you have J2SE security enabled, ensure that this directory is
accessible under your security policy.
If the directory you specify does not exist, Process Commander will attempt
to allocate it, but it is good practice to allocate the directory on the system
before specifying it here. The directory names you enter here are case
sensitive. Be sure to enter the names of the directories exactly as they
have been created on your system.
3. Save prconfig.xml.
35
Configuring the Oracle 9i/10g Client, version 9.2.0.5 or higher, for Process
Commander
This section applies new Process Commander installations using Oracle Client
version 9.2.0.5, as well as all later versions, including 10g.
Complete the following procedure to create an oracle.conf file and update

Process Commander’s prconfig.xml file.
1. Create the oracle.conf file.
The oracle.conf file contains the Oracle compatibility switch that allows the
9.2.0.5 client to access a database with the Date (type) column. This file must
also include the Process Commander user ID and password for access to the
file.
The format of the oracle.conf file is:
user=userid
password=password
oracle.jdbc.V8Compatible=true
Example:
user=pruser
password=pruserpassword
oracle.jdbc.V8Compatible=true
Note: Do not copy the file contents from this document and paste it into your
oracle.conf file. Hidden characters in this document can cause problems in
the text file.
The oracle.conf file may be located anywhere on the system. However,

Pegasystems recommends placing it in the same location as the prconfig.xml file.
This file is located under the contextroot directory in either the \WEB-INF\classes
subdirectory or the \APP-INF\classes subdirectory. For example for Tomcat, this
location is:
<app-server-install-root>\webapps\<contextroot>\WEB-
INF\classes\oracle.conf
Example:
D:\apache-tomcat-5.5.16\webapps\prdbutil\WEB-INF\classes\oracle.conf
2. Update the prconfig.xml file and the oracle.conf file with the User ID and
password. Edit the prconfig.xml file.
3. Enter the setting propertiesFile into the prconfig.xml file in the database
node. The original prconfig.xml file looks like this:
The propertiesFile setting holds the path to the oracle.conf file. Add it to the file
in the same section as the URL, name, and password information:
<env name="database/databases/PegaRULES/propertiesFile" value="D:\apache-tomcat-

5.5.16\webapps\prdbutil\WEB-INF\classes\oracle.conf" />
4. Save and close the prconfig.xml file.
Configuring UDB for Process Commander

UDB requires additional properties to be specified for the database connection.
Complete the following procedure to create an udb.conf file containing the
required properties and update Process Commander’s prconfig.xml file to
reference this file.
1. Create the udb.conf file.
The udb.conf file contains system properties that are required in this installation.
This file must also include the Process Commander user ID and password for
37
access to the file. Make sure the user you specify has appropriate grant and
execute privileges on the PRPC schema.
The format of the udb.conf file is:
user=<userid>
password=<password>
currentSchema=<user Db schema name>
currentFunctionPath=SYSIBM,SYSFUN,<user Db schema name>
Example:
user=pruser
password=pruserpassword
currentSchema=PRPC52
currentFunctionPath=SYSIBM,SYSFUN,PRPC52
Note: Do not copy the file contents from this document and paste it into your
udb.conf file. Hidden characters in this document can cause problems in the
text file.
The udb.conf file may be located anywhere on the system. However,

Pegasystems recommends placing it in the same location as the prconfig.xml file.
This file is located under the contextroot directory in either the \WEB-INF\classes
subdirectory or the \APP-INF\classes subdirectory. For example for Tomcat, this
location is:
<app-server-install-root>\webapps\<contextroot>\WEB-
INF\classes\udb.conf
Example:
D:\apache-tomcat-5.5.16\webapps\prdbutil\WEB-INF\classes\udb.conf
2. Update the prconfig.xml file and the udb.conf file with the User ID and
password. Edit the prconfig.xml file.
3. Enter the setting propertiesFile into the prconfig.xml file in the database
node. The original prconfig.xml file looks like this:

The propertiesFile setting holds the path to the udb.conf file. Add it to the file in
the same section as the URL, name, and password information:
<env name="database/databases/PegaRULES/propertiesFile" value="D:\apache-tomcat-

5.5.16\webapps\prdbutil\WEB-INF\classes\udb.conf " />
4. Save and close the prconfig.xml file.
Tomcat returns to the Environment Entries page.

39
Installing the PegaRULES Application (prweb.war)

Deploy the WAR file for the PegaRULES core application, prweb.war. The
procedure is the same as the one you completed for prdbutil.
1. Restart Tomcat, from the Tomcat home page click the Tomcat Manager
link to open the Tomcat Web Application Manager page, and scroll down to
the Deploy section:
2. In the section WAR file to deploy, click the Browse button to navigate to the
location of the prweb.war file and select it.
3. When the prweb.war file is displayed in the Select WAR file to upload field,
click Deploy to automatically install the application. Tomcat will deploy the
application into the \<tomcat_install_root>\webapps\prweb directory.
The application name will appear in the list of deployed applications.
Note: The name of the WAR file determines what Tomcat will use for the
context root value for the application.
4. When the application has been deployed, shut down Tomcat, and then
delete the prweb.war file from the \<tomcat_install_root>\webapps\
directory.
Tomcat uploads the WAR file to the webapps directory as part of the
deployment process. If you do not remove the WAR file after deployment,
Tomcat redeploys the application each time the server is restarted.
Edit the prconfig.xml for prweb

Repeat the edits you entered for prdbutil as described in “Installing the
PegaRULES Rule Import Application (prdbutil)” beginning on page 28 in the
prconfig.xml file in the prweb context. Be sure to complete the changes as
described in
– Configure the Database Connection on page 31
– Specify explicit temp directory in prconfig.xml on page 34.
The prconfig.xml file for prweb can be found in your Tomcat installation directory
under \webapps\prweb\WEB-INF\classes.
Important: You must make the same changes to the prconfig.xml file in the
prweb context that you made in the prconfig.xml file for prdbutil. Each
application uses a separate configuration file.
41
Installing the System Management and Online Help Applications

Deploy the online help application (prhelp.war) and System Management
application (prsysmgmt.war) in the same manner as the database import
application (prdbutil.war).
You do not need to edit prconfig.xml for these applications.
Note: The prhelp.war file is distributed in a ZIP file, DocumentationImage.zip,

which is separate from the Process Commander software distribution. If you
receive the software on CD, there will be a separate Documentation
Distribution CD. In DocumentationImage.zip file or on the Documentation
Distribution CD, the prhelp.war application is located in the archives directory.
You configure both applications to work within PegaRULES using the Configure
Help and JMX Applications link in the import application described below.
For more details on the System Management Application, refer to the System
Management Application Reference Guide.
Assigning the PegaDiagnosticUser Role to your System

Management Application Users
Users accessing the System Management Application in Process Commander
must be assigned the role PegaDiagnosticUser. If the user does not have this
role they will be challenged for authentication when they attempt to access the
System Management Application from Process Commander.
The role PegaDiagnosticUser is associated with the System Management

Application through a security-constraint element on the Diagnostic Data servlet
defined in the prweb.war application’s web.xml file:
- <security-constraint>
- <web-resource-collection>
<web-resource-name>Diagnostic Data</web-resource-name>
<description>Serves diagnostic files generated by the JMX
client</description>
<url-pattern>/DiagnosticData</url-pattern>
<http-method>GET</http-method>
<http-method>POST</http-method>
</web-resource-collection>
- <auth-constraint>
<role-name>PegaDiagnosticUser</role-name>
</auth-constraint>
</security-constraint>
If you do not want to restrict access to the System Management Application, edit
the web.xml file in the WEB-INF directory of the prweb.war deployment in your
application server and delete this security constraint element.
Note: Changing this setting in the web.xml file may require redeployment of
the PegaRULES Web Application.
If you want to restrict access to the System Management Application, use your
application server tools to assign the PegaDiagnosticUser role to any users that
must be able to access the System Management Application.
Next Steps
When your deployments are complete, continue with Chapter 5: Installing
Process Commander to complete the installation process.
43
Chapter 5:
Installing Process Commander
After deploying the Process Commander software components, you run the
Process Commander Rulebase Utilities application (prdbutil.war) to load the
initial PRPC rulesets to your database and verify your installation. This chapter
provides a step-by-step guide to completing the Rulebase Utilities tasks.
Complete Rulebase Utilities (prdbutil.war) Setup Steps

You will use the Process Commander Database Utilities to upload the Process
Commander application rulesets and install them in your database.
1. If necessary, start your application server.
2. If necessary, stop the Process Commander application.
3. Enter the URL for the prdbutil application in a browser window, for
example:
http://localhost:8080/prdbutil/index.html
You will see the initial page of the Database Utilities interface:
Note: This interface leads you through a checklist to verify your preparation
for installing the PegaRULES application rulesets, and then through a
series of steps that configure the system for use. Some steps include a
Skip button that allows you to move on to the next step without completing
the current one. During your first installation of Process Commander, do
not skip any steps. Review and, where necessary, complete each step
45
carefully.
In particular, be sure to complete Step 7, Setup Organization. In this step

you supply an Organization name that will be used to create initial users
and access groups for Process Commander. You use the user
Administrator@<your_organization_name>.com with the password ‘rules’
to log on to Process Commander for the first time. You can then use the
Process Commander facilities to configure other access groups and users.
4. Click Begin to display the Verify Database Connection page.
5. Click on Verify Connection
The utility displays “Checking Connection to the Database.” Results should

return in a few moments.
If it cannot make a successful connection, the utility displays an error screen:

You must have a working connection to your PRPC database to continue.

Exit from the utility, and contact your Database and Application Server
administrators to correct the problem, and then run the Database Utilities
again. For information on configuring your database and JDBC resources
see Chapter 2, “Preparing the Database Server” on page 10, and
“Configuring Database support on your Application Server on page 17.
If the connection is successful, the utility displays a screen like the following:
Use this screen to verify that

– you are connected to the correct database
47
– you are performing the expected Maintenance Action: Install.
It the database verification process identifies existing PRPC records with

data in the database, the utility assumes that the Maintenance Action is an
upgrade. If no data is found, the utility assumes the Maintenance Action is
an Installation.
6. Scroll down and click on Next to view the Installation checklist:
7. Read and check each checkbox to verify that you have completed the
prerequisites for the installation, then click Next at the bottom of the page.
Instructions for completing these tasks are given in the earlier chapters of
this Installation Guide.
PRPC displays the Upload Application Files page:

8. Use this page to load the PRPC JAR file to your application server. This
file contains the initial application rule sets that you will load to your
database.
– Click Browse, navigate to the PegaRULES/applicationJar/ directory of
your software distribution for 5.4 SP2, and select the PRPC JAR file, for
example:
PRPCv5_v54_relcand_0109.jar
The numbers at the end of the file name will be different than in this
example.
– Click Upload.
Note that this file is large and may take some time to be transferred to
your server.
– When the Upload completion page displays, click Done.
The page Process PegaRULES Process Commander Application Instances is

displayed:
49
9. Use this page to install the PRPC rule instances to your PRPC database:
– Confirm that the staging directory is the same as the directory to which
you uploaded the file PRPC jar file.
– Confirm that the PRPC jar file you uploaded is displayed in the Select
File field.
– Click Process
Process Commander begins to load the application Rule Base to your

database, and writes logging information to the Database Utilities page.
Important: Depending on the speed of your system and database, this

process can take anywhere from 45 minutes to over an hour.
If the installation is not successful, error messages are also written to the
screen. If the install fails to complete successfully, drop the tables that were
created and rerun this procedure. SQL scripts for each supported database
type are available on the distribution media to drop the PRPC tables in the
schema/DDL/ directory.
When the installation is complete, click Next on the confirmation page.

Process Commander displays the Configure Rule Search Indexing page.

51
10. Optionally, complete this form and click Create to enable Lucene search
capabilities in Process Commander, or click Skip to pass over this step.
This is an optional step. If your system has a very large number of rules or
work objects, enabling the Lucene search engine can improve the
performance of searches in the Process Commander interface.
Process Commander will display an update page while the index file is
imported. When the import is complete, click Next to continue.
Process Commander displays the Configure Help and JMX Applications

page:
11. Complete this page to specify the URLs to access the Help (prhelp.war)
and System Management (prsysmgmt.war) applications, and then click
Create to enable these applications. In most cases, you only need to
replace <port> with the Tomcat server port for your installation.
Note: The default URLs for the Help and System Management applications
specify only localhost as the server name. This will only allow users logged
into the same server on which the applications are deployed to access the
applications. Replace localhost with the appropriate server name and port
number in you want to allow access to the applications from other Process
Commander nodes.
These applications are accessed from the Process Commander interface. Either
application can be deployed to a different application server than the core
Process Commander application.
When the import is complete, click Next on the confirmation page.
Process Commander displays the Setup Organization page:

53
12. Enter the name of your organization in the appropriate field, and click
Preview to review the objects and users that will be created:
– Click Print to print a record of this page.
Important: Be sure to preview and record the information on this page.

The organization name you provide will be used to create the initial
users and access groups for your Process Commander system. You
will need to know the user names to log on and begin using your
Process Commander installation.
– Click Create to create the organizational structure that will be used to

initialize the Process Commander application.
When the Organization import is complete, click Next on the confirmation page.
Process Commander displays the Verify Installation page.
55
13. Click Verify.
A Waiting message displays while the utility verifies the ruleset loaded to the
database. The system checks the rows present in the database against the
rows required for this release. If all rows are present, the utility displays a
successful verification report:
If problems are found, error messages with instructions will be displayed.

14. Click Next.
Process Commander displays the Complete PRPC Installation Process page:
You can close the Database Utilities browser window.
15. Stop and restart the application server.
16. Ensure that all three Process Commander applications have started:
– prweb
– prsysmgmt
– prhelp
17. Access the Process Commander servlet, PRServlet, through a browser.

Type in the URL for Process Commander application. This will be of the
form: http://<server>:<portnumber>/<context_root>/PRServlet. For
example:
http://prpc-server:8080/prweb/PRServlet
If successful, you should see the PegaRULES login screen (PRServlet):

57
18. Login using the Administrator user created with your organization name
during the Installation process. Use the password rules.
19. Select one of the Welcome topics, or click Close to enter the Process
Commander application.
Continue with the next section to enable the System Management Application for
your installation.
Create a Systems Management Node

Identify a node for your Process Commander system in Pegasystems’ System
Management application to enable monitoring of the installation.
For more details on the System Management Application, refer to the System
Management Application Reference Guide available on the Pega Developer
Network (http://pdn.pega.com). Click PRPC System Tools in the navigation
menu on the left of the PDN home page to find a link to the guide.
59
20. In the Process Commander Developer Portal, click on Tools >System

Management Application.
The System Management Console opens. No nodes are set up initially.

21. Click on the + button at the top of the left pane to open the form for creating
a new node:
61
22. Complete this form by entering the information appropriate to your

installation of Process Commander. You must complete all required fields.
The example values above show the basic configuration for a Process
Commander instance on the same server as the prsysmgmt.war application.
You can also use this application to connect to remote instances of Process
Commander by supplying the appropriate information for the remote server
machine.
23. When complete, click on the Submit button to create your node:
24. To view data on this node, click the host name, in this case localhost, in the
navigation pane on the left. The console displays current data on this
system:
63
For information on all the functionality of the System Management Application,

refer to the System Management Application Reference Guide available on the
Pega Developer Network (http://pdn.pega.com). Click PRPC System Tools in
the navigation menu on the left of the PDN home page to find a link to the guide.
Next Steps
Refer to Administration and Security Guide

The Administration and Security Guide describes how to perform the initial
startup, setup, and day-to-day administration of your Process Commander
system.
In addition, there are two other procedures specific to 5.4 SP2 to be aware of:
Version Number Change for PegaRULES Application

The numbering convention for the PegaRULES application shipped with 5.4 SP2
has been changed to 05.04. In previous releases the application was shipped as
PegaRULES 5.4. To maintain compatibility with your rules that reference the
earlier application, PegaRULES 5.4 is also shipped with 5.4 SP2, but it is marked
for deprecation.
If you are migrating rules to this installation that reference PegaRULES 5.4, they
will continue to work. But you should change references to PegaRULES 5.4 to
PegaRULES 05.04, and new rules should also reference PegaRULES 05.04.
Update WorkHistoryVersion in Imported Work History Items
If you have work history items that were migrated from a 4.2 system or created in
a 5.x system that had the WorkHistoryVersion set to 4.2, you can improve the
performance of your system by converting them to the 5.1 format. For complete
information and procedures, see the History Upgrade Utility guide on the Pega
Developer Network:
http://pdn.pega.com/DevNet/PRPCv4/SystemTools/documents/HistoryUpgradeU
tility.pdf
Integration Information
Integrating with External Systems
PegaRULES Process Commander provides a set of standard integration
services for creating interfaces to and from external systems. The
documentation for these integration services is found in two places:
– The manual, Integrating with External Systems, describes the Process
Commander integration features and presents general concepts and
information for integrating Process Commander applications with other
systems.
– The Integration Services section of the Pega Developer Network (PDN)
presents individual documents for individual types of services and
65
connectors, along with appropriate RuleSet and code examples

demonstrating their use.

PRPC5-4SP2 J2EE Install Guide Tomcat

Încărcat de

Informații document

Descriere originală:

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

PRPC5-4SP2 J2EE Install Guide Tomcat

Încărcat de

Drepturi de autor:

Formate disponibile

PegaRULES Process Commander

Release V5.4 SP2

Installing on Tomcat Application Servers

June 26, 2008

Other brand or product names are trademarks of their respective holders.

This document is the property of:

Phone: (617) 374-9600

PegaRULES Process Commander

Chapter 1: Introduction ................................................................................................................. 1

Chapter 2: Preparing the Database ............................................................................................ 10

Chapter 3: Preparing the Application Server ............................................................................ 16

Chapter 4: Deploying Process Commander-Tomcat ................................................................ 20

Installing the PegaRULES Rule Import Application (prdbutil) ................................... 28

Chapter 5: Installing Process Commander ............................................................................... 43

■ To upgrade a Process Commander 4.2 system to 5.4 SP2, your current

■ For information about upgrading an existing Process Commander 5

These documents and any updates to existing Process Commander

2. Configure your application server and deploy the Process Commander

3. Load the Process Commander application rulesets to the database.

4. Perform initial configuration of the Process Commander system.

Process Commander Description

The deployment of a basic installation instance is shown in the diagram below:

Process Commander Core Component Versions

Type of deployment PRPC package to use

Existing deployments on WebSphere 6.x or WebLogic 9.x that prweb.war or

Tomcat users should install the WAR in all cases.

Overview of the Installation Procedure

1. Prepare the Database server

2. Prepare the application server

3. Deploy the PRPC components.

4. Install the Process Commander rulesets

5. Configure Your PRPC system

■ A working installation of the application server.

■ Configured relational database available for Process Commander use, and

Supported Process Commander Platforms

2. Review your site’s deployment requirements with your IT representatives.

3. Consult with your Pegasystems representative about your installation

Support During the Installation Process

■ A system administrator to provide network and computing resources.

You will need a system administrator with knowledge of your IT infrastructure

■ A database administrator to create and configure the Process Commander

You will need an experienced DBA with appropriate passwords and

■ An application server administrator to prepare the application server to

This resource must have administrative access to the application server

■ A Process Commander administrator to deploy the Process Commander

You will need an administrator/deployer who has knowledge of the

Check the Pega Developer Network for the Latest Information

Deployment information and updates

This page also includes links to WebEx recordings demonstrating the

Check Knowledge Base Platform Bulletins

WebLogic Issues 21352

A Note for PRPC 4.2 Users

■ Create a blank database.

Each of these steps is described in the following sections.

■ Install and configure the relational database according to vendor directions.

Creating a PRPC Database

■ Database server name

■ Database port number

The Process Commander system requires this information to access this

Additional UDB Requirements

■ Process Commander requires a buffer pool and temporary tablespace with a

If your use exceeds the page size, PRPC generates a PRRuntimeException

■ Process Commander requires a C++ compiler on the UDB database