pegarulesprocess commmanderinstallation guide - pega ....../user_projects/domains/domain-name/bin...

$: PegaRULESProcess CommmanderInstallation Guide - Pega ....../user_projects/domains/domain-name/bin Example: C:\Oracle\Middleware\user_projects\domains\pega\bin$
PegaRULES ProcessCommmander InstallationGuide

Version: 7.1.3

Database: DB2-LUW

Application Server: WebLogic

© Copyright 2013

Pegasystems Inc., Cambridge, MA

All rights reserved.

This document describes products and services of Pegasystems Inc. It may contain trade secrets and proprietaryinformation. The document and product are protected by copyright and distributed under licenses restricting their use,copying distribution, or transmittal in any form without prior written authorization of Pegasystems Inc.

This document is current as of the date of publication only. Changes in the document may bemade from time to time at thediscretion of Pegasystems. This document remains the property of Pegasystems andmust be returned to it upon request.This document does not imply any commitment to offer or deliver the products or services described.

This document may include references to Pegasystems product features that have not been licensed by your company. Ifyou have questions about whether a particular capability is included in your installation, please consult your Pegasystemsservice consultant.

For Pegasystems trademarks and registered trademarks, all rights reserved. Other brand or product names are trademarksof their respective holders.

Although Pegasystems Inc. strives for accuracy in its publications, any publicationmay contain inaccuracies ortypographical errors. This document or Help System could contain technical inaccuracies or typographical errors. Changesare periodically added to the information herein. Pegasystems Inc. may make improvements and/or changes in theinformation described herein at any time.

This document is the property of:

Pegasystems Inc.

One Rogers Street

Cambridge, MA 02142-1209

Phone: (617) 374-9600

Fax: (617) 374-9620

www.pega.com

Document: PegaRULES Process Commmander Installation Guide

Software Version: 7.1.3

Updated: Monday, December 09, 2013

Contents

About This Guide 3

Intended Audience 3

Documentation Resources 3

Platform Support Guide 3

Installation, Upgrade and Deployment Documentation 3

Installation Overview 4

Planning Your Install 4

Product mode 5

Automatic or manual DDL application 5

Split Schema 5

Optional database user for schema changes 5

Installation Prerequisites 6

PRPC Architecture 7

Database Server Setup 8

Database Prerequisites 8

About DB2 Database Users 8

Database Preparation 8

Create an Empty Database 10

Create User Accounts 12

Create a Database Schema 13

Installing the Rulebase 17

Rulebase Prerequisites 17

System Requirements 17

Running the Installation and Upgrade Assistant 18

Running the Command Line Script 25

Completing the Rulebase Installation 26

Application Server Setup 28

Application Server Prerequisites 28

Application Server Preparation 28

Set the JVM Memory Parameters 28

Edit the setDomainEnv Script or Batch file 28

Set an Explicit Temporary Directory 29

PegaRULES Process Commmander InstallationGuide 1

Enable AWT to support PRPC Graphical Reports 29

Put the JDBC Driver in the WebLogic Classpath 30

Configure the Application Server 30

Enable DNS Lookup 31

Create JDBC Resources 33

Configure JMS 40

Create a JMS Module 43

Create a Connection Factory and Subdeployment 46

Create a Topic and Subdeployment 49

Deploying the PRPC Application Archives 52

Deploy the PRPC EAR file, prpc_j2ee14.ear 52

Deploy the PRPCWAR file, prweb.war 59

Deploying the prsystmgmt.war and prhelp.war applications 65

Configure Split-Schema 65

Assign the PegaDiagnosticUser Role 66

Login to PRPC 67

Post Deployment Configuration 68

Enable Help and System Management Applications 68

Configure Directed Web Access 68

Configure Search Index Host Node Settings 69

Change the Administrator Password 69

Install Solution Frameworks 69


About This GuideThis guide describes how to install a new instance of PegaRULES Process Commander (PRPC) 7.1.3 on aDB2-LUW 10.1 database and a WebLogic 12c application server.

It does not describe how to perform an upgrade to an existing PRPC instance. That information is in thePRPC 7.1 Upgrade Guide.

Intended Audience

This guide is intended for anyone involved in the planning and installation of PRPC 7.1.3 includingresources that manage and administer your DB2-LUW database and WebLogic application server.

Documentation Resources

A variety of documentation and online resources are available to help you with your installation anddeployment process.

The Pega Discovery Network (PDN) is Pegasystems' online documentation and information site. It is thecentral depository for the review and download of updates to this guide and other installation anddeployment documentation.

To access the latest installation and deployment information, navigate tohttps://pdn.pega.com/resources/deployment-guides.

Platform Support Guide

Included with your distribution media and published on the PDN, the Platform Support Guide lists thedatabases and application servers supported for the 7.1.3 release.

It is important that you review this document before installing PRPC to verify that you are installing onsupported versions of your database and application server. To access the latest Platform Support Guide,click the Resources tab on the PDN and click the link under PRPC Deployment.

Installation, Upgrade and Deployment Documentation

7.1.3 release notes, deployment information and the latest versions of the installation and upgradeguides are available for review and download from the PDN.


https://pdn.pega.com/resources/deployment-guides

https://pdn.pega.com/resources/deployment-guides

Installation OverviewInstalling PPRC 7.1 is a multi-step process that involves configuring your database and applicationserver, loading rules into the database, and then deploying application archives to the application server.

Prior to installing PRPC:

n See the Platform Support Guide for a list of supported versions.

n Review the Planning Your Install topic in this section. This is particularly important when planningfor enterprise-scale systems with multiple nodes and/or environments.

This install guide is organized to expedite the installation process. It can be summarized in the followinginstall steps that are typically performed in sequence.

1. Configure the database

2. Load the rulebase

3. Configure the application server

4. Deploy PRPC archives

5. Configure PRPC

Some organizations follow specific governance procedures for the allocation and use of IT infrastructure,including databases and application servers. If your organization has special teams for managingdatabases and application servers, these resources should be engaged as early in the planning process aspossible. PRPC supports different deployment topologies and configuration options which impact how thesupporting infrastructure is configured and managed going forward.

Your PRPC distribution package contains a significant number of rules which are loaded into the databaseusing one of two methods:

n Installation and Upgrade Assistant (IUA)— The IUA is a graphical installer tool that guidesyou through the installation process. It is a Java swing application that can be run on both Windowsand Unix systems. This tool requires Java 6 or 7.

n Command Line — Scripts are provided for both Windows and Unix that allow installation onheadless (non-UI) environments and/or environments that require a scripted, repeatable processfor installation. This tool requires Java 6 or 7.

Both installation methods use a batch process to load the rulebase. Due to the magnitude of rules andother data objects which must be loaded, Pegasystems strongly encourages you to run the installer onthe same machine as the database server. If this is not possible, run the installer on a machine with fastdirect access to the database server. Do not attempt to run the installer on a virtual private network(VPN) or a multi-hop wide area network (WAN).

Planning Your Install

PRPC 7.1 supports a new runtime mode and a variety of deployment topologies that can impact thechoices you make at different stages of the installation process. Before installing PRPC, consider thefollowing:


Product mode

PRPC 7.1 introduces support for a new runtime mode — Multitenancy. The Multitenancy mode hasdifferent installation requirements, different runtime behaviors and different administrative procedures.This mode should not be selected without reviewing the Multitenancy Administration Guide whichdiscusses this mode in detail. It is included in your distribution package and available on the PDN.

Automatic or manual DDL application

The installer is designed to automatically render and apply schema Data Definition Language (DDL) toyour database. Optionally, DDL may be manually rendered via a command-line script and then appliedusing native or 3rd party tools.

If you intend to manually apply the DDL, do this prior to running the installer.

Split Schema

In 7.1, PRPC supports a split schema database configuration. In a split configuration, Rules and Data(including Work) are maintained in two schema. This configuration is required when using Pega 7's HighAvailability features and is generally recommended for organizations requiring minimal downtime whenupgrading PRPC.

Optional database user for schema changes

PRPC supports the use of an optional database account that is preferentially used by specific PRPCfeatures that modify the schema structure. This configuration provides greater auditability and control ofschema changes, but requires:

n the configuration of an additional database user account

n the configuration of a dedicated connection pool in the application server

The use of a second database user is supported for both single and split-schema configurations.


Installation Prerequisites

The prerequisites for installing PRPC are:

Application Server

l WebLogic Application Server. See the Platform Support Guide for a list of supported versions.

l A minimum of 2 GB memory

l PRPC web applications require a minimum of 2GB of memory to operate, although yourparticular memory requirements may be higher depending on the number of users and yourspecific configuration

l A minimum of 200 MB of disk space

l Make sure that you allocate enough storage to accommodate debugging and other loggingrequirements. In general, ensure that your logging configuration is such that logs are notwritten to the same directory as the application server runtime components.

Database Server

l DB2-LUW relational database. See the Platform Support Guide for a list of supported versions.

l A minimum of 5 GB storage

l The data schema that contains the PRPC work objects should be allowed to grow toaccommodate the page of work creation.

Database and application server time zone and character encoding

Configure your database server and app server to use the same time zone and character encoding toavoid conflicts.


PRPC Architecture

PRPC is a Java EE-compliant enterprise application that requires two main subsystems for its operation —an application server and a database server.

l The application server hosts PRPC’s application archives and also provides interconnectivity toother systems through various protocols.

l The database server stores the rules, data and work objects used and generated by PRPC.

Application users and developers typically access PRPC through a web browser. Applications may alsoexpose HTTP-based services (e.g. SOAP, REST or HTTP) for purposes of administration or processautomation in a headless environment.


Database Server SetupThis section lists the database prerequisites and describes how to create user accounts, the database anddatabase schema for your PRPC install.

Database Prerequisites

Before you configure your database, see the Platform Support Guide for a list of supported versions foryour database.

n DB2-LUW server is installed and running.

n An Instance Name has been defined.

n Java is enabled in the database.

n Operating System-level users are defined with the appropriate authorizations. See the topic AboutDB2 Database users below.

About DB2 Database Users

All users must also exist at the Operating System level. Before you actively configure DB2-LUW, makesure the appropriate OS-level users and authorizations are defined.

A typical DB2-LUW development instance usually involves creating two users at the Operating System-level:

• Instance owner – this user allows the creation of databases, schema, and database users. This usermust have Administrative privilege on the operating system — e.g., in Windows this user is a member ofthe Administrators Group.

• PRPC runtime user – this user is specified during the configuration of the JDBC data source on theapplication server, and is used to perform database operations on behalf of PRPC. This user (or users)must not have Administrator privileges on the operating system — e.g. do not associate the runtime userwith Administrators Group; otherwise, DB2 will report an error.

Note that you can have one or two users at runtime – see the topic Base vs. Admin User in the DatabasePreparation topic for more information.

Make sure you have configured at least the two Operating System users before attempting toconfigure database users in the next section.

Database Preparation

The database configuration process depends on three primary considerations.

1. Single vs. Split Schema

2. Base vs. Admin User

3. DDL application

Single vs. Split Schema

It is possible to configure PRPC 7.1 to access two schemas.


n a Rules schema, which contains the PRPC rulebase

n a Data schema, which contains both Data and Work instances

When possible, Pegasystems recommends the use of a split configuration particularly in critical softwaredevelopment life-cycle (SDLC) environments such as QA, STAGE and PROD.

A split-schema configuration is required to support PRPC’s High Availability features, namely rollingupgrade.

Base vs. Admin User

PRPC minimally requires one Base database user account which is used by the installer to load therulebase and also by the application server for normal runtime operation. If possible, it is best to use asingle database account.

However, PRPC is designed to accommodate an additional Admin user account which is preferentiallyused by certain PRPC features which modify the database schema.

To configure PRPC to use an Admin account, you create the account in the database with the appropriatepermissions, then configure a second JDBC data source in the application server using the new databaseaccount. With a Base + Admin user configuration, the Admin user is granted full privileges, while theBase user is granted a smaller subset.

For most runtime operations, PRPC will use the Base data source and user. If one of the featuresbelow is used, PRPC will choose the Admin data source and user.

The following features are preferentially accessed by the Admin account if two database accounts areconfigured.

n Schema Change Tracking tool — System > Database > Schema Change Tracking

n Optimize Schema tool — System > Database > Optimize Schema

n Modify Schema wizard — System > Database > Modify Schema

n Import wizard — Application > Distribution > Import

n Property optimization— See the PDN article How to expose a property as a database columnwith the Property Optimization tool

n Creating any new Circumstance Definition rule or defining a single circumstance on a rule. Theextended permissions are needed to support reporting on circumstanced properties. See the PDNarticle How to create a rule with multiple circumstance properties.

DDL Generation

The PRPC 7.1 installer is designed to automatically generate and apply the DDL. The DDL must be in placebefore the installer can load the Rulebase.

If you prefer to inspect and/or manually apply the DDL, you can use the packaged generateDDL scriptto create the DDL. This tool automatically renders the DDL and writes the output to a file. You can thenview and edit the file or directly apply it using any number of native or 3rd party database managementtools.


These instructions describe how to run the tool.

1. From a command prompt, navigate to the scripts folder of your PRPC distribution.

2. Type generateddl.bat or generateddl.sh to view script usage and options.

Example 1: Generating DDL for a single schema configuration

>generateddl.bat --action install --dbType udb --dbSchema Rules

Example 2: Generating DDL for a split-schema configuration

>generateddl.bat --action install --dbType udb --dbSchema Rules --dbDataSchemaData

The script writes the output to the following directory:

<PRPC_HOME>\schema\generated\udb

This directory is deleted and recreated each time the generateddl script is executed. If youwant to save a copy of the DDL, rename the directory prior to running the tool.

To prepare your DB2-LUW database server for use with 7.1, complete the following steps.

n Create an empty database

n Create database user accounts

n Create the database schema

Create an Empty Database

1. Launch the IBM Studio.

2. Right-click the database instance and select New Database...

The Specify instance details screen displays.


Enter the user credentials to connect to the instance.

The user must be first defined at the Operating System level and have Administrator privileges— e.g. in Windows, associate this user with the Administrators group.

3. Click Finish.

The Settings form Details tab displays.

Enter the following values:


Database name = <DBname>

Default buffer pool and table space page size = 32KB

Complete the Storage and Locale tabs with values appropriate for your environment.

By default, DB2 automatically manages storage and tablespace settings, expanding the sizewhen necessary. The default settings on these tabs are sufficient for most developmentenvironments and can be accepted as-is. If you want to use custom settings, configure a minimumof 5 GB in the User Table Space tab.

4. Click Run when you complete entry of your database information.

Create User Accounts

Use the Data Studio to create the database user accounts.

Before attempting to create the accounts, make sure they have been defined at the Operating Systemlevel. See the About DB2 Database Users section for more information.

1. In the Administration Explorer, expand the newly created database and the section namedUsers and Groups.

2. Right click Users and select Add and Manage User.


In the General tab, enter the Name of the database user.

This user (or users)must not have Administrator privileges on the operating system. Thismeans that if associate the runtime user with the administrators Group, otherwise DB2 will reportan error.

3. Select the Privileges tab.

Select DBADM.

Keep the remaining default values.

4. Execute the Change Plan.

Repeat these steps if you are planning to use a dual Base and Admin user configuration.

Create a Database Schema

Use the Data Studio to create the required schema objects.

You create either one or two schema depending on whether you are using a single or split schemaconfiguration.


1. In the Administration Explorer, expand the database object.

2. Right-click Schemas and select Create Schema.

In the General tab, enter the Name of the schema.


In PRPC 7.1, all table queries are schema-qualified. While the schema name itself is arbitrary,Pegasystems recommends choosing small names that are meaningful to your configuration. Forexample: in a split schema configuration, it is recommended that you name the two schema Dataand Rules.

3. Select the Privileges tab.

Configure the privileges for your database user.

In this example, the PRPC user is granted full permission to the Rules schema.

Accept the remaining defaults.

4. Execute the Change Plan.


Repeat these steps if you are planning to use a split schema configuration to create a secondschema.


Installing the RulebaseThis section describes how to install and load the PRPC rulebase.

The PRPC Rulebase can be loaded using either of the following methods.

n Installation and Upgrade Assistant (IUA)— uses a Java-based UI guided tool that sets up thePRPC Rulebase schema in the database and loads PRPC rules

n Command-line script— A command-line script is provided for both Unix and Windows platformsand is suitable for automating the installation process of installing PRPC in headless environments

Rulebase Prerequisites

Prior to running the installer — either the IUA or the command-line version — confirm you meet thefollowing prerequisites:

n Database users and roles are defined with the proper privileges

n A new database is defined with sufficient capacity

n Database schemas are defined

For a single schema configuration, you should have one schema for both rules and data objects

For a split schema configuration, you should have separate schema for rules and data objects

System Requirements

Because of the large volume of data loaded by the Installation and Upgrade Assistant (IUA), you shouldrun the installer or command-line install scripts on the same machine as the database server. If this isnot possible, run the tool on a system with fast, direct access to the database server.

The minimum systems requirements are:

n Windows or Linux operating system

n 1.25GB of memory

n 6GB of disk space

n Java Platform, Standard Edition Development Kit (JDK)

The installer creates a series of log files in <PRPC_HOME>\scripts\logs. If you encounter a problemwhile running the installer, copy the logs to a safe location before re-running the installer. The IUA re-creates this directory each time the installer is run.

The <PRPC_HOME>\.checksum directory provides an MD5 checksum for each the file in thedistribution. To verify that the distribution has been downloaded correctly, you can calculate a checksumusing the Jacksum tool www.jonelo.de/java/jacksum/.

For example: if your PRPC distribution was unzipped to <PRPC_HOME>:

java -jar jacksum.jar -m -a md5 -r -p -O outputFile.md5 <PRPC_HOME>


http://www.jonelo.de/java/jacksum/

Compare outputFile.md5 to the md5 file located in <PRPC_HOME>\.checksum. The checksumvalues should be identical.

Running the Installation and Upgrade Assistant

This section describes how to run the Installation and Upgrade Assistant (IUA) to install the rulebase.Before running the IUA, make sure you have met the database and system prerequisites.

1. Copy the distribution file to the computer that you will use to run the IUA. Extract the contents ofthe ZIP file into an empty directory.

If you are installing the software from the PRPC DVD included with your media distribution, copythe contents of the DVD to an empty directory.

2. Double-click the PRPC_Setup.jar file.

Alternatively, right-click the PRPC_Setup.jar file and select Open With > Java.

3. The IUA loads and the install icon appears in your task bar.

Throughout the install, you can click the buttons at the bottom of the screen to navigate fromscreen to screen, get install help or cancel the process. The recommended selection is indicated bythe button with a blue background.

n moves to the next screen

n goes back to the previous screen


n starts a process

n displays help for that screen

n cancels the install and exits the IUA

4. Click to display the License Agreement.

Scroll to read the agreement.

5. Click to accept it and move to the Installer Mode screen.

If you do not want to accept the agreement, click to exit the IUA.

On the Installer Mode screen, choose Installation. If you are performing an upgrade, see thePRPC 7.1 Upgrade Guide.


6. Click to choose your Database Type.


Select your database type.

7. Click to choose the Product Edition.

Select the PRPC edition you want to install.

PRPC Standard Edition— this option installs a new instance of PRPC 7.1. It is the defaultselection.

PRPC Multitenancy Edition— this option installs PRPC 7.1 in a specialized mode designedtosupport Software As A Service (SaaS) runtime environments. See the PRPC 7.1 MultitenancyAdministration Guide on the PDN for more information.

Upgrading or migrating from one edition to another is not supported. If you install one editionand later decided to use a different edition, you will need to drop and recreate the databse orcreate a new database. The schema DDL between the two editions are not compatible.

8. Click to set up your database connection.


Complete the fields to specify the database connection to your PRPC database.

Some of the fields on this screen — in particular the JDBC Driver Class Name and theDatabase JDBC URL— are pre-populated based on the type of database you selected on theprior screen. If you edit these or any other fields on this screen and later decide to change thedatabase type, the IUA may not populate the fields correctly. If this occurs, you can enter thecorrect field values as documented below or exit and re-launch the IUA, selecting the intendeddatabase type.

JCBC Driver Class Name — Enter the JDBC driver class name.

The IUA will attempt to pre-populate this field for you as com.ibm.db2.jcc.DB2Driver. If thefield does not populate correctly, manually enter the class name or exit and re-launch the IUA.

JDBC Driver JAR File — Enter the full path to the appropriate driver file for your database type

and version. Click to browse and select the file. See the Release Notes for a list ofsupported drivers.

Database JDBC URL— Enter the JDBC connection URL for your PRPC database.

The IUA will attempt to pre-populate this field asjdbc:db2://serverName:50000/db:fullyMaterializeLobData=true;fullyMaterializeInputStreams=true;progressiveStreaming=2;progressiveLocators=2;useJDBC4ColumnNameAndLabelSemantics=2;. If the field doesnot populate correctly, manually edit the field or exit and re-launch the IUA.


Database Username and Password— Enter the user name and password for the PRPC user onyour database.

Make sure you have configured the database user you use during the installation with full read,write and administration permissions. The user must have acess to the schema for the PRPCdatabase. In particular, the database operator used to connect to the database during the installmust be explicitly granted privileges that allow them to create user defined functions.

Rules Schema Name (Required)— Enter the name of the Rules schema in the PRPC database.

Data Schema Name (Required)— Enter the name of the Data schema in the PRPC database.

If you are installing into a single schema, the value for the data schema name should beconfigured to match the value of the Rules Schema Name.If you are installing into a split schema, those values should be different, corresponding to theschema you defined in the database.

When you have completed entry of the database connection values, click . If theconnection is not successful, review your connection information, correct any errors and retest.

9. If the connection is successful, click to choose how you want to apply the databaseschema.

By default, the IUA is designed to automatically generate and apply the schema DDL to yourdatabase. If the DDL is already defined in the database, select the Bypass Automatic DDLApplication option. Otherwise, leave the box unchecked.


10. Click to enter the System Name.

Complete the following fields.

System Name — Enter a name for your PRPC system.

Production Level — Enter a production level. Depending on the type of installation, choose:

5 for a system that will be used in production

4 for a pre-production system

3 for a test system

2 for a development system

1 for an experimental system

The Production Level affects many security features of your system. Both the System Name andProduction Level can be changed through PRPC once the system is running.

The System Name can be accessed from the System > Settings > System Name landing page. TheProduction Level can be updated from the App Explorer by typing Data-Admin-System in the searchfield and then selecting SysAdmin > Class > Data-Admin-System to open your system.

11. Click to begin the Rulebase Load.


Click to start the rulebase load. Installation logs automatically appear in this window.

The rulebase load time can last for several hours and will vary widely based on network proximityto the database server. The log window may appear inactive when the IUA is processing largerfiles. When the load is complete or if there is an issues during installation, a message box appears.If there is an issue, copy the installation log from the temporary directory to a safe location beforeexiting the IUA.

12. Click to close the IUA.

Running the Command Line Script

To use the install.bat/.sh script, you configure the setupDatabase.properties file and run the script.

1. First edit the setupDatabase.properties file.

You can find the setupDatabase.properties file in the scripts directory of your distribution, .e.g<PRPC_HOME>\scripts\setupDatabase.properties

2. Open a command prompt and navigate to the scripts directory.

3. Type install.bat or ./install.sh to run the script.

The installation of the rulebase can take several hours, depending on the proximity of the database to thesystem running the install script.


Completing the Rulebase Installation

When the install process completes successfully, the install will report performance metrics for each stepof the installation process. See the example below.

When you see these log messages you know that you installation has successfully completed.


Application Server SetupThis section describes how to configure your WebLogic Application Server for use with PRPC 7.1.3.

n Prerequisites

n Preparation

n Configuration

n Deploying PRPC Archives

Application Server Prerequisites

Before you start to set up your application server, confirm that the following prerequisites have beenmet.

n You have installed a supported JDK. See the Platform Support Guide for a list of supportedversions.

n Confirm or set a JAVA_HOME environment variable that points to the directory where the JavaJDK is installed.

n You have installed a supported version of the WebLogic application server. See the PlatformSupport Guide for a list of supported versions.

n You have created your WebLogic domain.

Application Server Preparation

Complete the following procedures to set configuration properties in the WebLogic environment that arerequired by PRPC.

These procedures describe a typical method for setting configuration properties in a basic WebLogicinstallation by modifying the setDomainEnv file. More complex WebLogic installations may use differentstartup scripts. If you are unsure about your environment, review this section with your WebLogicadministrator to determine the appropriate script in which to enter these options so they are read duringstartup.

Set the JVM Memory Parameters

Edit the setDomainEnv file to increase the amount of system memory allocated to the applicationserver running PRPC. The following minimums are recommended.

l Minimum Heap Size (-Xms): 2048MB

l Maximum Heap Size (-Xmx): 4096MB

If your application server is using the Sun JVM as recommended, also add the PermSize andMaxPermSize settings.

l PermSize (-XX:PermSize): at least 64MB

l MaxPermSize (-XX:MaxPermSize): at least 384MB.

Edit the setDomainEnv Script or Batch file

Edit the files as follows:


1. Open the setDomainEnv file, setDomainEnv.cmd for Windows or setDomainEnv.sh for UNIXplatforms, in a text editor.

These scripts are located in the bin directory of your WebLogic domain.

<app-server-install-root>/user_projects/domains/domain-name/bin

Example:

C:\Oracle\Middleware\user_projects\domains\pega\bin

2. Find the setting for USER_MEM_ARGS:

@REM IF USER_MEM_ARGS the environment variable is set, use it tooverride ALL MEM_ARGS values

if NOT "%USER_MEM_ARGS%"=="" (set MEM_ARGS=%USER_MEM_ARGS%)

3. Before the override setting, add the line set USER_MEM_ARGS= to specify the memory settingsas follows:

set USER_MEM_ARGS=-Xms2048m –Xmx4096m -XX:PermSize=64m -XX:MaxPermSize=384m

For example:

@REM IF USER_MEM_ARGS the environment variable is set, use it tooverride ALL MEM_ARGS valuesset USER_MEM_ARGS=-Xms2048m –Xmx4096m -XX:PermSize=64m -XX:MaxPermSize=384mif NOT "%USER_MEM_ARGS%"=="" (set MEM_ARGS=%USER_MEM_ARGS%)

4. Save the file.

Set an Explicit Temporary Directory

In the SetDomainEnv file, create a JVM property to set an explicit Temporary directory for PRPC. Thisdirectory is used by PRPC to store static data during a session. It is important that it be properly specifiedand accessible to the Process Commander user

In the setDomainEnv.cmd file for Windows or the setDomainEnv.sh file for UNIX platforms, add theline set EXTRA_JAVA_PROPERTIES=-Dpega.tmpdir= and specify the full path to a directory youhave allocated, for example:

set EXTRA_JAVA_PROPERTIES=-Dpega.tmpdir=C:\PegaTemp\pr_temp

Enable AWT to support PRPC Graphical Reports

Add or modify your JAVA_OPTIONS setting to include:


–Djava.awt.headless=true

For example, add the following line to the setDomainEnv.cmd (Windows) or the setDomainEnv.sh(UNIX) file:

set JAVA_OPTIONS=%JAVA_OPTIONS% –Djava.awt.headless=true

Put the JDBC Driver in the WebLogic Classpath

For PRPC to connect to the relational database, the database driver(s) must be in the WebLogic classpath.

1. In the setDomainEnv.cmd (Windows) or the setDomainEnv.sh (UNIX) file, add the line setEXT_PRE_CLASSPATH= and specify the path to db2jcc.jar. Using EXT_PRE_CLASSPATH ensuresthat the system finds and uses this JDBC driver.

For example, your setting will look similar to the following:

set EXT_PRE_CLASSPATH=C:\Oracle\Middleware\user_projects\domains\pega\lib\db2jcc.jar

This JDBC driver is the Type 4 universal driver: db2jcc4.jar.

2. Save and close the setDomainEnv file.

Configure the Application Server

This section and the following sections describe the steps you take in the WebLogic AdministrationConsole to configure the server and deploy the PRPC application archives.

For more information about installing and using the WebLogic Administration Console, see the OracleWebLogic documentation athttp://www.oracle.com/technetwork/middleware/weblogic/documentation/index.html

1. Start the Administration server for the PRPC domain.

You can start the Administration Server by running the appropriate startWebLogic script,startWebLogic.cmd (Windows) or startWebLogic.sh (UNIX,) in the bin directory of yourdomain directory, for example:

Oracle\Middleware\user_projects\domains\<domain>\bin

On Windows, you can also start the Administration server from a shortcut on the Start menu byselecting Oracle WebLogic > User Projects > your domain > Start Admin Server for WeblogicDomain.

2. Start the Administration Console and login with the administrative user name and password thatyou specified in the Configuration Wizard.

You can start the Administration Console in a browser by opening the URLhttp://hostname:port/console where hostname is the name of the Administration Server and portis the listen port on which the Administration Server is listening for requests — port 7001 is thedefault.


http://www.oracle.com/technetwork/middleware/weblogic/documentation/index.html

Enable DNS Lookup

The PRPC Tracer 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, perform the following steps.

1. In the Admin console navigate to Environment > Servers > AdminServer > Configuration > Tuning.

The Tuning settings page displays.


2. On the Tuning page:

If Configuration editing is not enabled, in the Change Center click Lock & Edit.

l Select the Reverse DNS Allowed checkbox.

l Click Save on the Settings page.

If configuration is not enabled, in the Change Center click Activate Changes.

A confirmation message displays on the AdminServer page.


Remain in the Administration Console to continue preparation of the application server.

Create JDBC Resources

Complete the following steps to create a JDBC Data Source and Connection Pool to allow PRPC to connectto the PRPC database.

1. In the Administration Console, under Domain Structure, select Services > Data Sources.

The Summary of JDBC Data Sources page displays.

If configuration editing is not enabled, in the Change Center click Lock & Edit.

2. On the Data Source page click New. Select the Generic Data Source option.

The Create a New JDBC Data Source page displays.


3. Complete this page.

l In the Name field, enter PegaRules

l In JNDI Name, enter jdbc/PegaRULES

l Select DB2 as the Database Type.

4. Click Next to select the Database Driver.

The JDBC Data Source Properties page displays.


From the list of available drivers, select the Database Driver suitable for your database type. Ifyou are not sure which driver to choose, check with your database administrator.

If you choose an XA driver to enable two-phase commit, you must install the prpc_j2ee14.earfile as the core PRPC application archive. If you are using XA drivers, you should also increase themaximum connections specified for the connection pool associated with the JDBC data sourcedefined for PRPC to more than 60. See your application server documentation for instructions.

5. Click Next.

A Transactions Options page displays. The options that appear depend on the type of driver youselected.

6. Unless instructed otherwise by your site database administrator, accept the defaults for thetransaction options and click Next.

The Connection Properties page displays.


7. Complete this page.

l In the Database Name field, enter the name of the PRPC database.

l In the Host Name field, enter the name or IP address of the database server.

l In the Port field, enter the port number to be used to connect to the database server.

l Enter the User Name and Password of the PRPC user you created for the database.

8. Click Next.

The Test Database Connection page displays.


9. Confirm the values that have defaulted into the page.

10. Update the Properties text box to add the connection properties:

Specify the current Schema by listing the currentSchema, property specifying the DB userschema name, and the currentFunctionPath property specifying SYSIBM,SYSFUN,and the DBuser schema name:

currentSchema=<SCHEMANAME>,currentFunctionPath=SYSIBM,SYSFUN,<SCHEMANAME>

For example, if the schema name is PRPC, the connectionProperties would be:

currentSchema=PRPC;currentFunctionPath=SYSIBM,SYSFUN,PRPC

Be sure to enter the schema name in all capital letters, as in the example.

Note: SYSIBM and SYSFUN are system schemas provided by DB2. They are required because PRPCmakes use of some functions made available in these schemas.

DB2 UDB versions 9.5 and 9.7 require four additional settings:


l fullyMaterializeLobData=true

l fullyMaterializeInputStreams=true

l progressiveStreaming=2

l progressiveLocators=2

You can add these settings as additional connection properties or as parameters in the URL.

To specify these settings as connectionProperties, add these to the connection properties field.

To add these settings as parameters to the connection URL, append them to the URL as semi-colonseparated properties:

url=jdbc:db2://sysvol2:50000/PRPC:fullyMaterializeLobData=true;fullyMaterializeInputStreams=true;progressiveStreaming=2;progressiveLocators=2;

Note: The currentSchema and currentFunctionPath properties must be specified as aconnectionProperties setting, and cannot be entered into the URL.

11. Click Test Configuration.

If the test is successful, click Finish to return to the Summary of JDBC Data Sources page.

If the test is not successful, review your settings and retest.

12. If configuration is not enabled, in the Change Center click Activate Changes.

13. Click the name of the data source you just created in the Data Sources table.

14. On the Settings page for the data source, click the Connection Pool tab.



15. Verify that the Connection Pool properties are correct for the data source you created. Modify themif needed.

16. Select the Targets tab and select the AdminServer as the target for the data source.

If you have configured managed servers in your domain, target them instead of the AdminServer.


17. Click Save. If configuration is not enabled, in the Change Center click Activate Changes.

Configure JMS

If you are deploying PRPC's EAR archive, prpc_j2ee14.ear, complete the following procedure toconfigure JMS for use by PRPC.

If you are deploying PRPC’s WAR archive, prweb.war, you do not need to configure JMS resources. Skipthis section and go to the topic, Deploying the PRPC WAR file, prweb.war.

PRPC's EJB components use JMS Services internally. If you are deploying the EAR archive, you mustcomplete this procedure even if your PRPC application does not use messaging to integrate with externalsystems.

To configure the JMS resources required by PRPC:

1. Create a JMS Server targeted at your WebLogic server.

2. Create a JMS Module.

3. Create JMS Resources

l a Connection Factory and subdeployment, targeted to the JMS Server

l a Topic and subdeployment, targeted to the JMS Server.

Create a JMS Server

1. On the Administration Console, under Domain Structure, select Services > Messaging > JMSServers.


2. Click New to create a new server.



3. In the Name field, enter a name to identify the PRPC JMS server — PRJMS_Server in this example.Click Next.

4. In the Target dropdown, select your Admin Server. Click Finish to return to the Summary ofJMS Servers page.



5. Confirm that you see the message, JMS Server created successfully. If configuration is notenabled, in the Change Center click Activate Changes.

6. Click Home to return to the Domain home page.

Create a JMS Module

1. On the Administration Console, under Domain Configurations, select Services > Messaging >JMS Modules.

This will become the container for the connection factory and topic.



2. Click New to create a new module.

3. On the Create JMS System Module page, enter a name — PRJMS_Module in this example. ClickNext.

4. In the Targets table, select the checkbox for Admin Server. Click Next.



5. Check the Would you like to add resources to this JMS system module? box. Click Finish.

The Settings page for the JMS Module displays.

6. Confirm that you see the message The JMS module was created successfully.



Create a Connection Factory and Subdeployment

1. Still on the Settings page for your JMS Module. Click New in the Summary of Resources table.


The Create a New JMS System Module Resource page displays.

2. Select Connection Factory, Click Next.

3. Enter a Name for the Connection Factory — PRAsyncConnectionFactory in this example.

Enter the JNDI Name as jms/PRAsyncTCF. Click Next.


4. Click Advanced Targeting.

5. Click Create a New Subdeployment.


6. Under Subdeployment Properties, enter a Subdeployment Name — PRJMS_Subdeployment inthis example. Click OK.

You return to the Properties page for the Connection Factory.

7. Under Targets, select the checkbox for the JMS Server you created for PRPC. Click Finish.

You return to the Settings page for your JMS Module.


8. Confirm that you see the message Connection Factory created successfully.

If Configuration editing is not enabled, in the Change Center click Activate Changes.

Create a Topic and Subdeployment

To create a JMS Topic and Subdeployment in this JMS Module, repeat the procedure you just completedfor the Connection Factory.

1. On the Settings page for your JMS Module, click New in the Summary of Resources table todisplay the page Create a New JMS System Module Resource again.


2. From the list of resource types, click Topic. Then, click Next.

The Create a New JMS System Module Resource page displays for the topic.


3. Enter a name for the Topic, such as PRAsyncTopic.

Enter the JNDI name as jms/PRAsyncTopic. Click Next.

4. Select Create a New Subdeployment.

5. On the Create a New Subdeployment page, enter a new name for the subdeployment — asPRJMS_Subdeployment_Topic in this example. Click OK.

Use a different name than the one you used for the Connection Factory Subdeployment. TheConnection Factory and the Topic should each have their own subdeployment.


6. Under Targets, select the checkbox for the JMS Server you created for PRPC. Click Finish.

You return to the Settings page for your JMS Module.

7. Confirm that you see the message The JMS Topic was created successfully.



You have now completed the configuration tasks for your WeblogicApplication Server.

Deploying the PRPC Application Archives

This section describes how to deploy the PRPC application archives and set up a dignostic role for usersfollowing the configuration of your WebLogic application server.

The archives you deploy include:

l the PRPC Application

l the System Management Application

l the Online Help Application

You can deploy either the prpc_j2ee14.jar or prweb.war file as the core application archive. Do notdeploy both archives.

Deploy the PRPC EAR file, prpc_j2ee14.ear

Skip this procedure if you are planning to deploy the PRPC WAR file.

1. In the Domain Structure panel, click Deployments.


2. Click Install.


3. Click the upload your file(s) link.

4. Next to the Deployment Archive field, clickBrowse button to navigate to the archives directoryof your PRPC distribution.

Select the prpc_j2ee14.ear. When the file name is displayed in the Deployment Archive field,click Next.


5. On the Install Application Assistant, confirm the upload path and that the radio button next tothe archive name is selected and click Next.

6. Select Install this deployment as an application. Click Next.

The Optional Settings page displays.


7. Click Next to accept the defaults.


8. Leave Yes, take me to the deployment's configuration screen selected.

Review the settings to confirm that they are as expected.

Click Finish to begin deploying the application.

When the archive deploys, you return to the application’s Settings page.


9. Review the Overview page to confirm that the settings are as expected.

10. Click on the Targets tab to verify that the target server for the application is correct.

11. Click on the Overview tab again, and click Save.

12. In Domain Structure, click on Deployments to return to the Summary of Deployments page.


13. Continue with the deployments of the System Management and Online Help applications.

Deploy the PRPC WAR file, prweb.war

Skip this procedure if you are planning to deploy or have already deployed the PRPC EAR file.

1. In the Domain Structure section, click Deployments.

2. If Configuration editing is not enabled, click Lock & Edit to unlock the page. In the Deploymentstable, click Install.


3. In the Install Application Assistant, click the link upload your file(s).

4. Click the Browse button next to the Deployment Archive field, use the file dialog to navigate tothe archives directory of your Process Commander distribution.

5. Select the prweb.war file and click Open. When the file name is displayed in the DeploymentArchive field, click Next.


6. Make sure the radio button next to prweb.war is selected and click Next.

7. Select Install this deployment as an application and click Next to display the optionalsettings page:


8. Make sure the Name is prweb and click Next to accept the defaults.


9. Leave Yes, take me to the deployment's configuration screen selected and review that theother settings are as expected. Then, click Finish to begin deploying the application.

When the WAR file has deployed, your are returned to the application’s Settings page.


10. Review the Overview page to confirm that the settings are as expected.

11. Click on the Targets tab and verify that the target server is correct.

12. Click Save in the Assistant or Activate Changes in the Change Center to save the configuration.

13. In the Domain Structure panel, click Deployments again to continue with the deployments of


the prsysmgmt.war and prhelp.war applications.

Deploying the prsystmgmt.war and prhelp.war applications

Repeat the deployment procedure described for prweb above to deploy the two other PRPC applications,System Management prsysmgmt.war and Online Help prhelp.war.

Do not start these applications after deployment.

For more details about the System Management Application, see to the System Management ApplicationReference Guide on the PDN.

Configure Split-Schema

WebLogic uses a Deployment Plan to configure the JNDI setting in the application archive. ADeployment Plan is a user configurable XML file that captures environment-specific configurationproperties. If you plan to configure WebLogic to use a split-schema configuration follow these steps.

1. Create or edit a Deployment Plan.

2. Configure a specific directory structure for teh Deployment Plan and the EAR/WAR archive.

3. Deploy (or redeploy) the application archive and Deployment Plan using the WebLogicAdministration Console or the command line.

1. — Edit the Deployment Plan

Your PRPC 7.1 distribution is packaged with a sample deployment plan that you can use for yourenvironment. The deployment plan is located in the following directory:

EAR: <PRPC_HOME>\archives\weblogic\ear\prpc\Plan.xml

WAR: <PRPC_HOME>\archives\weblogic\war\prpc\Plan.xml

1. Make a copy (backup) of the sample plan, in case you need to back out your changes.

2. Open Plan.xml in a text editor, and locate the elements named defaultDataSchema anddefaultRulesSchema. Add the values for your schema in the <value> element. For example:

3. Save Plan.xml.

2. — Configure the Directory Structure

If you plan to deploy the WebLogic archive and Deployment Plan using the WebLogic AdministrationConsole, youmust use a specific directory structure.


Your PRPC 7.1 distribution includes a preconfigured structure. So you should not have to recreatethe required directories. However, if you maintain your WebLogic EARs (or WARs) in a separate location,you will need to replicate the proper directory structure.

The directory structure is :

<someDirectory>\app\prpc_j2ee14_WL.ear

<someDirectory>\plan\Plan.xml

The names of <someDirectory> and the EAR file can change, but the directory structure and name ofthe deployment plan, Plan.xml, cannot.

3. — Deploy the Archive

To deploy the WebLogic archive with a Deployment Plan using the WebLogic Console, login to the consoleand deploy the archive as described elsewhere in this document.

However, instead of selecting the EAR or WAR file, you will select <someDirectory>. For example, ifyou are deploying the archive from the PRPC 7.1 distribution, you select either:

EAR: <PRPC_HOME>\archives\weblogic\ear

or

WAR: <PRPC_HOME>\archives\weblogic\war

WebLogic will automatically include both the EAR (or WAR) file and the Deployment Plan (Plan.xml) whenyou select the directory. You can also deploy the archive and Deployment Plan using the command linetool weblogic.Deployer. See the WebLogic documentation for more information.

Assign the PegaDiagnosticUser Role

Users accessing PRPC's System Management Application (SMA) must be assigned thePegaDiagnosticUser role. If the user does not have this role they will be challenged for authenticationwhen they attempt to access the SMA from PRPC.

By default, the deployment configuration assigns the PegaDiagnosticUser role to administrative users. Ifyou want to restrict access to the SMA, use your application server tools to assign the role to any otherusers that must be able to access it.

The role is associated with the SMA through a security-constraint element on the Diagnostic Data servletdefined 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 JMXclient</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 theWEB-INF directory of the prweb.war deployment in your application server and delete this securityconstraint element.

In EAR file deployments, the web.xml file is located in the prweb.war file packaged inside the prpc_j2ee14.ear file.

Changing this setting in the web.xml file may require redeploying of the PegaRULES Application.

Login to PRPC

Log into the PRPC web application, replacing the <server> and <port> values with your specific values.

http://<server>:<port>/prweb/PRServlet

The PRPC log in screen displays.

Use the following credentials to log in.

User ID: [email protected]

Password: install

After logging in, PRPC automatically launches a process to index the rules in th system to support full-text search. While this process is running — usually 10-15 minutes to complete depending on yoursystem configuration …—you may notice some delay in the responsiveness of the PRPC user interface.


Post Deployment ConfigurationThis section describes the post deployment activities that are performed in the system once you havecompleted the setup and configuration of your WebLogic application server and deployed the PRPCarchives.

n Enable Help and System Administration applications

n Configure Directed Web Access

n Configure search index host node settings

n Change the administrator password

n Install solution frameworks

Enable Help and System Management Applications

The Help and System Management web applications are accessed from the PRPC interface through a URL.Either application can be deployed to a different application server than the core PRPC application.

To enable these applications

1. From the button, select System > Settings > URLs.

2. In the Online Help URL field, enter the URL for the Help application in the format:

http://<host>:<port>/prhelp

3. In the SMA URL field, enter the URL for the System Management Application in the format:

http://<host>:<port>/prsysmgmt

4. Click Submit.

You must log out of PRPC and log back in for these changes to take effect.

Configure Directed Web Access

Directed Web Access (DWA) allows external users that do not have a PRPC Operator ID to process anassignment in your application on a one-time basis. The URL you specify here is provided in an email tothe external user to access PRPC and may identify a proxy server.

To configure DWA

1. From the button, select System > Settings > URLs.

2. In the Public Link URL field, enter the URL that you want to provide in emails in this format:

http://<host>:<port>/PRServlet

3. Click .

You must log out of PRPC and log back in for these changes to take effect.


Configure Search Index Host Node Settings

Search indexing supports the full-text search facility in PRPC for rules, data instances, and work objects.By default, search indexing is enabled and indexing starts automatically when you start the applicationserver after deploying PRPC.

Host node settings are set by default to your PRPC node, and the Index directory is set toPegaRULESIndex in your PRPC temporary directory.

You can change the default settings on the Search tab of the System – Settings landing page. To access

this page, select > System > Settings > Search.

Change the Administrator Password

Because the default password for the system administrator is widely published, it is important to protectyour system after an installation by changing the password for the [email protected] operator ID.

To change the password

1. From the Operator Menu located to the right of the Designer Studio header, select the Profileoption.

2. Click Change Password.

3. Verify the Current Password, then enter and confirm the New Password.

4. Click Save.

Install Solution Frameworks

If you are installing one of Pegasystems Solution Frameworks as part of your PRPC developmentenvironment, install the framework now.

Follow the instructions in the Installation Guide provided on the distribution media for the Framework.


pegarulesprocess commmanderinstallation guide - pega ....../user_projects/domains/domain-name/bin...

Documents