Process Commander Installation Guide - WebSphere 7 and DB2 · 2019-05-22 ·...

Process Commander - z/OS

Installation GuideVersion: 6.3

Database: DB2 on z/OS

Application Server: WebSphere 7

Contents

Introduction 1

Check the Pega Developer Network for the Latest Information 1

Pegasystems Documentation 1

Deployment information and updates 1

Pegasystems Training 1

Overview of the Installation Procedure 1

1. Preparation Phase 2

2. Rulebase Setup Phase 3

3. PRPC Configuration Phase 3

Notes for Users of Earlier Process Commander Versions 3

Optional: Move System Settings from Configuration Files to Database 4

Process Commander Deployment Architecture 4

Process Commander Core Component Versions 5

Step1. Environment Considerations 7

Prerequisites 7

z/OS Configurations 8

Configure your environment 8

Manage Code Page Translations 9

Identify z/OS User IDs 10

Best Practice: Create Two Users 10

Collect Parameter Settings for Your Environment 10

Identify Pega Properties 10

Step 2: Database Preparation 14

Overview of the Process Commander Components 14

ii

Setting Process Commander Parameters 16

Creating the PRPC Database Step-by-step 17

1. Allocate space to storage groups 17

2. Create the z/OS libraries for Process Commander 17

3. Prepare the PRPC Software Distribution 18

4. Move the library files from the distribution to the mainframe 18

5. Set parameters in the PARMLIB library 22

6. Verify the environment 26

7. Create the Database Schema 26

To create the database schema from z/OS 26

To create the database schema from Windows. Linux, or Unix 30

Start Work Load Manager 32

Next Steps 32

Step 3: Application Server Preparation 34

Verify the Java Environment 34

Configure Support for the Process Commander Database 34

Create a WebSphere Profile 35

Start and Configure the Application Server 36

Set JVM Requirements 37

Create URL Providers 44

Create JDBC Resources 49

Create a JDBC provider 49

Create Data Source 52

Configure WebSphere WorkManager 65

Set HTTP transport channel custom property CookiesConfigureNoCache to false 68

iii

Process Commander Version 6.3

Deploy the PegaRULES core application 73

Deploying prpc_j2ee14_ws.ear in WebSphere 74

Installing the System Management and Online Help Applications 83

Assigning the PegaDiagnosticUser Role to your System Management Application Users 90

Next Steps 93

Steps 4 to 9 - Rulebase Setup 94

Install the Process Commander Schema and Rules in the Database 94

Move the Process Commander Software Distribution to Your Computer 94

Update Java 6 JDK to JAX-WS API 2.2.5 95

Rulebase Setup Using the Installation and Upgrade Assistant 95

Step 10 - Final Settings in Process Commander 112

Start and Login to Process Commander 112

Configure Process Commander 113

Enable Developer Help and the System Management Application 114

Optionally Set Search Index Host Node Settings 115

Create an Organization 117

Change the password for [email protected] 117

Install Solution Frameworks 118

iv

IntroductionThis document describes how to install a new instance of PegaRULES Process Commander 6.3.Upgrading an existing Process Commander installation is described in other documents:

For information aobut upgrading an existing Process Commander 5 z/OS installation to 6.3 seeProcess Commander z/OS Upgrade Guide 5.x to 6.3

For information aobut upgrading an existing Process Commander 6 z/OS installation to 6.3 seeProcess Commander z/OS Upgrade Guide 6.x to 6.3

These documents and any updates to existing Process Commander documentation are available on thePega Developer Network (pdn.pega.com).

Check the Pega Developer Network for the Latest InformationBefore beginning your installation procedure, check the Pega Developer Network (PDN), located athttp://pdn.pega.com, for the latest information. The installation guides are updated whenever newinformation becomes available. Be sure to check for the latest version.

Pegasystems DocumentationThe latest Process Commander documentation, including Installation, Upgrade, and Platform Supportguides is available on the Documentation page of the Pega Developer Network.

Visit http://pdn.pega.com and select Guides -> Process Commander V6 Deployment.

Deployment information and updatesCheck the Deployment page on the Pega Developer Network for information, updates, and platformbulletins on deploying Process Commander including links to the latest Knowledge Base articles.

Visit http://pdn.pega.com and select Browse -> Deployment -> About This Topic.

Pegasystems TrainingA range of Pegasystems course offerings are available to increase the effectiveness of your deploymentand development team members. For more information, visithttp://www.pega.com/Services/EducationalServices.

Overview of the Installation ProcedureThe following outline details the steps in the 6.3 installation process:

Preparation Phase

Step 1 – Environment Considerations

Step 2 – Database Preparation

Step 3 – Application Server Preparation

1

Introduction

Rulebase Setup Phase

Step 4 - License Agreement

Step 5 - Type of Setup

Step 6 - Database Configuration

Step 7 - Database Connection

Step 8 - System Name and Production Level

Step 9 - Rulebase Loading

PRPC Configuration Phase Step 10 – Final Settings in PRPC

1. Preparation PhaseYou complete the Preparation Phase following the procedures in this guide.

Step 1: Environment Considerations

Make sure that your environment meets the requirements for PRPC 6.3 in terms of: Hardware, OS, JVM,JDBC Driver, Application Server, Database Server, PRPC, and their respective settings.

1. Review the current Platform Support Guide, which is available on the Pega DeveloperNetwork (PDN) or from your Pega account executive. This document lists the recommendedsoftware components needed to support Process Commander, and any special requirementsor known issues with particular vendors or versions.

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

3. Consult with your Pegasystems representative about your installation plans. Pegasystems’prior experience with various platforms and deployment architectures can help yourinstallation go smoothly.

Step 2: Database Preparation

Create and configure an empty database for Process Commander to use. You can use SQL scriptsprovided by Pegasystems to create the schema required by Process Commander in the database, or youcan choose to have the Installation and Upgrade Assistant create the schema when you run that tool.

You provide connection information for this database to the Installation and Upgrade Assistant used inthe Rulebase Setup Phase and to specify the datasource in your application server. The connectioninformation you will need includes the location of the JDBC driver file, the driver class name, thedatabase connection URL, and the database user's username and password.

Note:When the Database Preparation is complete, Step 3, the Application Server Preparation, and Steps 4-9 inthe Rulebase Setup Phase can be performed in either order or simultaneously. You can, for example, launch theRulebase Setup process in Step 9 of the Assistant and then configure your Application Server while the Rulebaseload process is running.

However, you must configure the application server and deploy the Process Commander applications before youcan complete Step 10, PRPC Final Settings.

2


Important: You must be careful not to start the deployed Process Commander applications while the Rulebaseloading process is still running on the database. Note that your application server may start the applicationautomatically when it is deployed. If the Process Commander application attempts to connect to the databasewhile the Rulebase is loading, the database loading will not complete correctly.

Step 3: Application Server Preparation

Configure your application server to support the Process Commander application, including:

1. Configure the right Database Driver for your Database

2. Configure the PRPC Data Source

3. Configure other Java EE Application Server settings

4. Deploy the Process Commander application (WAR or EAR)

5. Deploy the online help application (prhelp.war) and System Management Application(prsysmgmt.war).

2. Rulebase Setup PhaseYou complete the Rulebase Setup Phase by running steps 4 to 9 in the Installation and Upgrade Assistant(PRPC_Setup.jar). This tool is covered in this guide in the section Steps 4-9, Rulebase Setup Phase.

The Installation Assistant optionally creates the Process Commander schema in the database instanceyou provide, and loads the initial set of rules and classes Process Commander needs to run into thedatabase.

3. PRPC Configuration PhaseYou complete the PRPC Configuration Phase after finishing the Installation by logging into ProcessCommander. The setup steps you should complete in Process Commander are described in section Step10: Final PRPC Configuration Steps.

Notes for Users of Earlier Process Commander VersionsThis installation procedure differs from earlier installation procedures in significant ways. Please reviewthe instructions carefully.

In particular, please be aware of the following changes:

Pegasystems now recommends using JDBC data sources defined in your application server toestablish connections to your database instead of the Process Commander connection poolingas specified in the prconfig.xml configuration file.

3

Introduction

Be sure to create and configure a temporary directory that Process Commander can use tostore static data. See the section “Setting the Explicit Temporary Directory” in the chapter thatdescribes deployment with your application server.

Optional: Move System Settings from Configuration Files to DatabaseIn 6.2, System Settings you may have added to the prconfig.xml or prbootstrap.propertiesconfiguration files as "env" elements should be moved to Dynamic System Settings (Data-Admin-System-Settings). Settings in your current prconfig.xml or prbootstrap.properties files willcontinue to work, and you can move the settings to Data-Admin-System-Settings instances at anytime. Pegasystems provides a utility that can move the settings automatically from theconfiguration files to Data-Admin-System-Settings instances.

Moving the settings to the database has several advantages.

Since the settings are stored as Data- instances, they can be read from the database by allnodes running your Process Commander installation. All nodes will have the same settingvalues, unlike the values in the prconfig.xml file which apply only to the node where that file islocated.

The values of the settings can be viewed and modified from Process Commander. Values storedin the configuration files must be changed by editing the file, which sometimes requiresredeploying the Process Commander application.

For complete information on System Settings and the procedure to convert your settings, see the"Configuration Settings Reference Guide" for Version 6.2. You can find this document on the PegaDeveloper Network by going to Resource Library > Tech Papers.

Process Commander Deployment ArchitectureProcess Commander is a Java EE enterprise application. As shown in the diagram below, it runs on top oftwo main platform sub-systems:

1. A database system to store the rules and work objects used and generated by ProcessCommander.

2. An application server that supports the Java EE specification. The application serverprovides a run-time environment and other services, such as database connections, JavaMessaging Services (JMS) support, and connector and services interfaces to other externalsystems.

4


Both developers working on Process Commander applications and users working with those applicationsaccess Process Commander through Web browser interfaces.

Process Commander Core Component VersionsThe Process Commander core application is packaged in four different versions to support deploymentinto different Java EE environments. The following table summarizes the packages provided and theiruse:

Type of deployment PRPC package to use

All Tomcat deployments prweb.war

New deployments on WebSphere 6.1.x, 7.0.x. prpc_j2ee14_ws.ear

New deployments on WebLogic 9.x, 10.3.1, 11g (10.3.2); JBoss CE 4.2.x, 4.3.x, 5.0.x prpc_j2ee14.ear

New deployments on JBoss EAP 4.3.x, 5.0.x (Red Hat) prpc_j2ee14_jbossJBM.ear

5

Introduction

Pegasystems strongly recommends deploying the EAR file for all deployments other than Tomcat.

You must deploy the EAR file:

in WebSphere 6 or 7 (with or without J2SE and Java EE security options), or

if you plan to use any of the following Java EE container-managed features in your applications:

Two-phase commit

JMS message services

Service EJB rules (Rule-Service-EJB rule type)

Important: You must deploy the EAR file in the WebSphere application servers. WebSphere's strictimplementation of the Java EE specification does not support use of the Process Commander WAR file.The Process Commander EAR file is designed for use in WebSphere systems.

In the supported application servers other than WebSphere, you can successfully deploy the WAR file forlimited use. In particular, you must disable Java 2 security in the application server when using aPRPC WAR archive. Deploying and configuring the EAR file ensures that you can add advanced Java EEfeatures as your application evolves or when you migrate to a production environment.

6


Step1. Environment Considerations

PrerequisitesThe 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 1GB of free memory. This is in addition to anymemory allocated for the operating system or other applications on the server. The memoryrequired for your system may need to be higher, depending on the number of users and yourspecific configuration.

A working installation of WebSphere 7.Process Commander Installation Guides for each supported application server are availablewith your Pegasystems software distribution and on the Deployment page of the PegaDeveloper Network (http://pdn.pega.com).

A DB2 on z/OS database configured for Process Commander use, and support in yourorganization for the installation and configuration of relational databases.

The application server platform may be z/OS, LINUX, UNIX or Windows systems.

A Windows system is required for the Pegasystems developer and end-user clients.

7

Step1. Environment Considerations

z/OS ConfigurationsComplete the following configurations before continuing the installation.

Configure your environment1. Your environment must support batch SPUFI (SQL Processing Using File Input) and batch

compile procedures.

The Process Commander jobs include a batch SPUFI procedure, PEGAINST, and a batchcompile procedure, PEGHSQL, both included in the PEGA.DB2.PROCLIB library. Bothprocedures are controlled by parameter settings you supply in the USERENV member of thePEGA.DB2.PARMLIB library.

2. Your site must support SQL-based stored procedures.

Jobs are provided to support either native or external stored procedures. If you useexternal stored procedures for the Process Commander system, this support requires, forinstallation purposes only, that a C compiler is available on z/OS.

3. If you use external stored procedures for the Process Commander system, work with yourDB2 DBA to select a Work Load Manager (WLM) Application Environment Name for thisdatabase.

You specify this WLM as the #WLMAPPENV property in the PEGPROPS member of thePARMLIB library. See, 5. Set parameters in the PARMLIB library on page 22.

After tailoring the JCL, ensure that the WLM proc is correctly installed in a systemProcedure library. PRPC will not start if the PRPC stored procedures will not run.

4. To support User Defined Functions (UDF) installed by PRPC, provide a dedicated Java-enabled Work Load Manager (WLM). Work with your DB2 DBA to select a Work LoadManager (WLM) Application Environment Name for this database and complete the systemconfiguration. For example:

Define the WLM application for PRPC to the system WLM with the WLM utility tool.

Ensure that the new WLM Application is part of the WLM Policy that is in effect onthe z/OS L-Par for PRPC.

You will specify this WLM as the #UDFWLM property in the PEGPROPS member of thePARMLIB library. See, 5. Set parameters in the PARMLIB library on page 22.

After the UDF have been defined and their jars loaded into the DB2 catalogs during thePRPC installation process, you must refresh this WLM application. See

8


5. Ensure that you have enabled New Function Mode on your DB2 for z/OS Version 8 orVersion 9 subsystem.

6. Pegasystems recommends the following ZPARM settings for any DB2 subsystem supportingour products. Some of these parameters apply only to Version 9. Contact your DB2 for z/OSsystem programmer and ensure that the following ZPARM values have been evaluated:

CACHEDYN=YES

CMTSTAT MAY BE INACTIVE OR ACTIVE

DESCSTAT=YES. (Mandatory)

IDBACK=200 (Minimum)

IDFORE=200 (Minimum)

IDTHION=300 (Minimum if CMTSTAT=INACTIVE)

LOBVALA=10240 (minimum)

LOBVALS=2048 (minimum)

NUMLKTS=5000 (Minimum)

NUMLKUS=30000 (Minimum)

OPTIOWGT=ENABLE

OPTIXOPREF=OFF

OPTXQB=OFF (TEMPORARY A/O 5/09 DUE TO IBM APARS)

STATCLUS=ENHANCED

SKIPUNCI=YES (V9 Only)

Manage Code Page TranslationsImportant: If you are installing to a UNICODE database, you must be sure that the appropriatecode page translation is set up across all tools used on the platform, including FTP, TSO, andSPUFI. Note that SPUFI is used to apply SQL to the database by JCL jobs. All of the JCL jobs usedin the PRPC installation use SPUFI to apply SQL in batch TSO.

9

z/OS Configurations

Identify z/OS User IDsProcess Commander requires z/OS log-on credentials to create the DB2 database and to access it oncecreated. You provide this username and password in the DBPROPS member of PARMLIB library, asdescribed below, and when you configure data access for Process Commander in your applicationserver.

These credentials need to have permissions to perform the following actions:

Log onto IBM’s Time Sharing Option (TSO)

Run z/OS batch jobs

Allocate Datasets (both z/OS and zFS)

Log onto IBM’s Unix System Services (USS)

Update OMVS (USS) memory size to 2 GB (RACF example ASSIZEMAX 2147483647)

DB2 database CREATE, DROP and ALTER authority, if not at the database level then for allobjects within a database

DB2 database INSERT, UPDATE and DELETE authority.

DB2 database grant access to create and execute stored procedures and user definedfunctions.

Best Practice: Create Two UsersYou can create two users with whose only difference is the database authority granted:

A user id known as the database owner, #DBOWNR, with permissions to issue SQL CREATE,DROP and ALTER commands against the Pega database instance.

A second user id, known as the database user, #DBUSER, with permissions to issue SQLINSERT, DELETE, UPDATE, and SELECT statements.

Collect Parameter Settings for Your EnvironmentIdentify Pega Properties

Working with your DBA and Data security team, identify your selections for each of the followingvariables. Enter your updates in the middle column as documentation for your installation. Later in theInstallation procedure, you enter these values in the PEGPROPS member of the PARMLIB library.

10


Note: The default values listed here, for example, for primary and secondary space allocations, have been testedby Pegasystems andwill support the initial installation and validation of a PRPC system. As your uniquerequirements, and use case, evolve, some of these values may change.

Variable with DefaultYourChoice

Description

LOB Parameters

#BLBBFP=BP4 Blob Buffer Pool (4K)

#BLBBP16=BP16k0 Blob Buffer Pool (16k)

#BLBLCK=LOB Blob Locksize

#BLBLCM=0 BLOB Lock Max

#BLBLOG=YES BLOB Logging

#BLBPRI=720 Blob Primary Allocation in pages

#BLBSEC=7200 Blob secondary allocation in pages

#BLBSTG=Blob.storage.group.name Blob DB2 Storage Group

Index Parameters

#IDXBP=BP2 Index Buffer Pool

#IDXPRI=720 Index primary allocation in pages

#IDXSEC=7200 Index secondary allocation in pages

#IDXSTG=Index.Storage.Group.Name Index DB2 Storage Group

Table Space Parameters

#TSPLCK=PAGE Table space Lock size

#TSPLCM=0 Table space lock maximum

#TSPPRI=720 Table space primary allocation in pages

#TSPSEC=7200 Table space secondary allocation in pages

#TSPSTG=Table.Storage.Group.Name Table space storage group

#TSP4BP=BP5 Table space 4k Buffer pool

#TSP8BP=BP8K0 Table space 8k Buffer pool

#TS16BP=BP16K0 Table space 16k Buffer pool

#TS32BP=BP32K Table space 32k Buffer pool

Database Access Parameters

#CCSID=EBCDIC EBCDIC or UNICODE

#DBNAME=PEGDB Database Name

#DBOWNR=PEGDBDBO Database Owner

11

z/OS Configurations

Variable with DefaultYourChoice

Description

#DBUSER=PEGDB PRPC Database user

#SYSADM=SYSADM System admin User

Package Collection for Stored Procedures

#COLLECTION=collection.name Collection ID for Stored Procedures

Work Load Manager Parameters for external stored procedures

#SPLOAD= the.same.as.the.USERENV.DB2LOAD.property

The load library of your stored procedures.This is the same value as the USERENV DB2LOAD property.

#WLMAPPENV=wlm.application.environment.name WLM Application Environment

#SSID=DB9G DB2 Subsystem ID

#DB2HLQ=DSN910 DB2 System Datasets HLQ

Work Load Manager Parameters for UDF support

#UDFWLM=wlm.application.environment.name

WLM Application Environment

Configure a dedicatedWLM for UDF support. This should be aseparate WLM from the one configured for external storedprocedures or the default system WLM.

Pay particular attention to #DBNAME, #DBOWNR, #DBUSER, #SYSADM, and #SSID:

#DBNAME is the name that your DBA will give your database and must match your sitestandards. The value you select here will be substituted everywhere in the target libraries thatDB2 expects a valid database name. PRPC has no special requirements for this name otherthan that it be acceptable to DB2. This installation procedure assumes that the entire databasecan be dropped and recreated. Carefully consider placing any non-PEGASYSTEMS relateddatabase objects in this schema.

#DBOWNR will be the database owner for the libraries copy of the PRPC database. This installprocedure assumes that #DBOWNR has DBADM on #DBNAME either directly via grant orindirectly via Secondary Authorization ID processing.

The PRPC application servers can logon to this database using #DBOWNR. Note that thisinstallation procedure will create a PLAN_TABLE owned by #DBOWNR.

#DBUSER will be the PRPC database accessor id. If your site t strictly enforces segregation ofduties, this userid can be used to run the PRPC applications. #DBUSER can only issue DML(select, insert, delete, update) commands while #DBOWNR can issue DDL as well as DML.#DBOWNR will create a set of synonyms for use by #DBUSER.

12


#SYSADM is a user id that has create database with grant privileges on the target subsystemrepresented by #SSID and #Location. #SYSADM is assumed to have both the create databaseand grant privilege.

#SSID is the unique system identifier that allows allied address spaces to connect to a specificDB2 subsystem.

By default, this installation will:

Disable the lock escalation feature. Should you wish to enable it, simply change #BLBLCM and#TSPLCM to a non-zero positive integer before tailoring the libraries. See the DB2 for z/OSmanuals for details on setting this value.

Assign separate storage groups for table spaces, index spaces, and LOB table spaces. Shouldyou wish to keep all three object types in a single storage group, set #BLBSTG, #IDXSTG, and#TSPSTG to the same value before tailoring the JCL.

Segregate each object type into its own 4k buffer pool. For the LOB buffer pools werecommend setting the Deferred Write Threshold “DWQT” to zero. By default, this installationprocedure defines all LOB table spaces as LOG YES. Pegasystems recommends segregatingLOB table spaces into their own buffer pools to ensure maximum system efficiency.

This installation process assumes that PRPC will connect to the database using the #DBOWNRuserid. If you wish to use #DBUSER see chapter 4 for the details on the changes necessary.

13

z/OS Configurations

Step 2: Database PreparationImportant: Complete configuration of your environment

Before continuing, be sure you have configured your z/OS environment as recommended inConfigure your environment on page 8

To prepare your database server to use with Process Commander, you must complete the followingtasks:

1. Allocate space to storage groups

2. Create the z/OS libraries for Process Commander

3. Prepare the Process Commander software distribution

4. Move the library files from the distribution to the mainframe

5. Set parameters in the PARMLIB library

6. Verify the environment

7. Create the Database Schema

Overview of the Process Commander ComponentsTo prepare the Process Commander database on z/OS you create a database and generate the schemarequired for the initial Process Commander Rulebase. Loading the Rulebase is described in section“Steps: 4-9: Rulebase Setup—Loading Process Commander Rules into the Database” on page 81.

This section gives you an overview of the components you will use in the upgrade procedure. Step-by-step instructions for creating and configuring these libraries are given below in Creating the DatabaseStep-by-step, on page 18.

To create the database and schema you allocate and load the following libraries from the ProcessCommander software distribution to your z/OS environment. You find these libraries in the directoryschema/db2zos/libraries:

PEGA.DB2.PARMLIB

The Pega Parameter library contains members, (DBPROPS, PEGPROPS, USERENV, andUPGFILES) which provide a single point to enter site-specific information needed to create aDB2 database for a Process Commander installation.

14


For a full inventory of the members of this library see “Pega Parameter Library(PEGA.DB2.PARMLIB) Members” on page 101.

PEGA.DB2.CNTL

The Pega Control library contains the JCL code that is used to create a DB2 database for aProcess Commander installation.

For a full inventory of the members of this library see “Pega Control Library (PEGA.DB2.CNTL)JCL Members” on page 103.

PEGA.DB2.DDL

The Pega Database Definition Library contains members that control the execution of DB2utilities for creating a DB2 database for Pega installation.

PEGA.DB2.PROCLIB

The Pega Procedure library contains the procedures executed by the JCL in the Pega Controllibrary to create a DB2 database for installing Pega Rules.

In addition, you allocate and load two product-specific libraries that contain the media required to definethe database components necessary to install Process Commander 6.3.

PEGA.PEG63.DDL

This library contains DDL (Database Definition Language) members that provide the SQLdefinitions needed to create all the database components for Process Commander 6.3, exceptthe stored procedures.

You create this library by moving the contents of schema/db2zos/EBCDIC/install orschema/db2zos/UNICODE/install, depending on the format of your database, to the libraryyou allocate in your z/OS environment.

PEGA.PEG63.SOURCE

This library’s members contain the source necessary to create all the database storedprocedures needed for Process Commander 6.3.

You create this library by moving the contents of schema/db2zos/EBCDIC/install/source orschema/db2zos/UNICODE/install/source, depending on the format of your database, to thelibrary you allocate in your z/OS environment.

Similar product libraries will be distributed to prepare the database for the ProcessCommander Frameworks Solutions.

15


Setting Process Commander ParametersBefore running the JCL jobs that build the Process Commander database definition, you provideinformation about your environment in following two properties members in PEGA.DB2.PARMLIB.

You use the PEGPROPS properties member to specify database parameters used by theProcess Commander system, including the following:

DB2 LOB parameters

DB2 index parameters

DB2 table space parameters

DB2 database access parameters

DB2 stored procedure collection parameter

DB2 Work Load Manager (WLM) parameters

You supply the name of the PEGPROPS member in the environment member, USERENV, in thePROPNAME variable. It is recommended that you name this member the same name as yourdatabase name.

You use USERENV, the user environment member, to specify parameters that identify yourenvironment to the Pega JCL used to create the Process Commander DB2 database instance.Copy this member to a member name that matches the database owner’s id. The databaseowner’s id is the TSO/Batch user id name under which the database is to be created.

This member identifies the following general Process Commander resources in your Pega JCLenvironment:

The Pega base libraries.

The Pega product libraries that contain the statements to define the Pega databaseinstance for the appropriate Pega product, in this case Process Commander 6.2 SP1.

The database properties file used to provide connection information for the ProcessCommander database.

The site’s naming conventions for the required DB2 system libraries.

The site libraries to build and then execute the Pega stored procedures.

The following section provides step-by-step instructions for creating the database.

16


Creating the PRPC Database Step-by-step1. Allocate space to storage groupsIdentify the database space requirements for an initial install. Ensure that the Storage Groups andBuffer pools selected for use by Process Commander are created, and permission is granted to the#DBOWNR userid to use them.

Allocate at least 5GB to the database and, if possible, allow the database to grow. This minimumsize allows you to load the initial Process Commander RuleBase and do simple development.

Important: Monitor the database use carefully. As development begins, the size of the databasewill need to be increased significantly.

For your reference, Appendix B, “Pega Database Tables, Views, Triggers and Stored Procedures”contains a listing of the database elements initially created, including their size and page size.

2. Create the z/OS libraries for Process CommanderPre-allocate the following datasets to simplify the process of moving the Process Commanderlibraries to z/OS. The DCB information must be as given below:

PEGA.DB2.CNTL– DCB=(DSORG=PO, LRECL=80,BLKSIZE=6400)– DCB=(DSORG=PO, LRECL=80,BLKSIZE=6400)

PEGA.DB2.PARMLIB– DCB=(DSORG=PO, LRECL=80,BLKSIZE=6400)– DSNTYPE=LIBRARY,SPACE=(CYL,(1,1))

PEGA.DB2.PROCLIB- DCB=(DSORG=PO, LRECL=80,BLKSIZE=6400)- DSNTYPE=LIBRARY,SPACE=(CYL,(1,1))

PEGA.DB2.DDL- DCB=(DSORG=PO, LRECL=80,BLKSIZE=6400)- DSNTYPE=LIBRARY,SPACE=(CYL,(1,1))

PEGA.PEG63.DDL- DCB=(DSORG=PO, LRECL=80,BLKSIZE=6400)- DSNTYPE=LIBRARY,SPACE=(CYL,(1,1))

PEGA.PEG63.SOURCE- DCB=(DSORG=PO, LRECL=80,BLKSIZE=6400)- DSNTYPE=LIBRARY,SPACE=(CYL,(1,1))

PEGA.PEG63.UDFJAR

17


- DSORG=PS RECFM=VB LRECL=32756 BLKSIZE=32760- DSNTYPE=LIBRARY,SPACE=(CYL,(1,1))

3. Prepare the PRPC Software Distribution

1. Determine a location that has FTP access to your z/OS system on a Windows desktop, aLinux for System Z desktop, or z/OS .

2. Download the Process Commander image, for example, 113990_prpc63.zip, or copy it fromyour Pegasystems software CD, to that location.

3. Expand 113990_prpc63.zip to expose the directory structure of the software distribution.For example, you can use the Java jar command to decompress the archive as follows:

jar –xf 113990_prpc63.zip

This command expands the archive in the current working directory.

4. Move the library files from the distribution to the mainframe

1. Transfer the following files from the distribution to the corresponding library you allocatedon your mainframe:

schema\db2zos\libraries\PEGA.DB2.CNTL

schema\db2zos\libraries\PEGA.DB2.DDL

schema\db2zos\libraries\PEGA.DB2.PARMLIB

schema\db2zos\libraries\PEGA.DB2.PROCLIB

2. Transfer all the files in the following directories to the appropriate library in your z/OSenvironment. Use the appropriate directory, EBCDIC or UNICODE, depending on the formatof your database:

schema\db2zos\EBCDIC\install or schema\db2zos\UNICODE\install toPEGA.PEG63.DDL

schema\db2zos\EBCDIC\install\source orschema\db2zos\UNICODE\install\source to PEGA.PEG63.SOURCE

3. Copy the Process Commander install SQL commands to PEGSQL

schema\db2zos\EBCDIC\install\db2zos_install_63.sql orschema\db2zos\UNICODE\install\db2zos_install_63.sql to PEGA.PEGSQL

18


4. From your PRPC software distribution, transfer archives/udf/prreadstream.jar to thelibrary PEGA.PEG63.UDFJAR you created above.

For example, to transfer the files using FTP, use the commands below to FTP the files from the PRPCDistribution directories to the allocated libraries:

From PRPC Distribution Directory To Library FTP Command

schema\db2zos\libraries\PEGA.DB2.CNTL PEGA.DB2.CNTL mput *

schema\db2zos\libraries\PEGA.DB2.DDL PEGA.DB2.DDL mput *

schema\db2zos\libraries\PEGA.DB2.PARMLIB PEGA.DB2.PARMLIB mput *

schema\db2zos\libraries\PEGA.DB2.PROCLIB PEGA.DB2. PROCLIB mput *

schema\db2zos\EBCDIC\install orschema\db2zos\UNICODE\install PEGA.PEG63.DDL mput PEG*

schema\db2zos\EBCDIC\install\db2zos_install_63.sql orschema\db2zos\UNICODE\install\db2zos_install_63.sql

PEGA.PEGSQL put db2zos_install_63.sql PEGSQL

schema\db2zos\EBCDIC\install\source orschema\db2zos\UNICODE\install\source PEGA.PEG63.SOURCE mput *

archives/udf/prreadstream.jar PEGA.PEG63.UDFJAR put archives/udf/prreadstream.jarPEGA.PEG63.UDFJAR

Note: Managing Code Page Translation

If you are installing to a UNICODE database, you must be sure that the appropriate code pagetranslation is set up for the FTP transfers. For example, include the FTP SBDATACONN statementto specify the file_system_codepage for the current, and the network_transfer_codepage for thetarget system.

For example, if you are tranferring the PRPC files from a local system to a z/OS system, use thefollowing FTP sequences:

1. Upload all folders from ../schema/db2zos/libraries using ftp in ascii in the standardsequence.

ftp zoscasciipromptcd ‘PUSER2.DB2.CNTL’mput *quit

19


Important: Do not use quote the site sbdataconn statement when uploading theselibraries because it corrupts the contents of the Rexx programs included in those folders.

2. Upload files from ../schema/db2zos/UNICODE/install using ftp subcommandsincluding the site sbdataconn statement in this sequence:

ftp zoscasciiquote site sbdataconn=(ibm-1148,iso8859-1)promptcd ‘PUSER2.DB2.INSTALL.DDL’mput *quit

Note: This is an example only. Be sure to specify code page tables that are appropriate foryour site.

3. Upload files from ../schema/db2zos/UNICODE/install/source using ftpsubcommands including the site sbdataconn statement in this sequence:

ftp zoscasciiquote site sbdataconn=(ibm-1148,iso8859-1)promptcd ‘PUSER2.DB2.INSTALL.SOURCE’mput *quit

Note: Converting UNIX EOL Character to Windows

If you expand the Process Commander distribution on a Windows system, you must convert thefiles from the Unix end-of-line (EOL) character, LF, to the Windows format, CR/LF, before you canFTP them to your z/OS system.

If you do not stage the software distribution on a Windows system, you can FTP the files as theyare in the software distribution.

If your site does not already have a standard utility to perform this conversion, there are manyfree tools available to do Unix2Dos conversion. If necessary, Pegasystems provides a bat file,crlf.bat, and ANT script, crlf.xml, in the 'scripts' directory, to perform this conversion.

Follow these steps to convert the end-of-line characters using Pegasystems' crlf script:

20


1. In a Windows command-line console, change directory to the scripts directory of yourProcess Commander distribution. For example, if your Process Commander distribution hasbeen expanded into C:\PRPC63 then issue "cd C:\prpc63\scripts" from a command window.

2. Type crlf

crlf.bat creates 2 files in the scripts\logs directory, crlf.log and crlf.rpt. If the logssubdirectory of the scripts directory does not exist crlf.bat will create it.

crlf.log contains a log of the script's execution. crlf.rpt contains the detailed Ant reportlisting the modified files.

3. When the script completes, use Notepad to open any schema file, for example, PEGBND inC:\PRPC63\schema\db2zos\EBCDIC\install. If the display shows a nicely formatted set ofbind commands then the conversion is complete.

Example FTP Session

The following is a example of an FTP session in a Windows command prompt window that movesthe files correctly to a mainframe. In the example, information you enter is highlighted. Modifythe entries as needed for your environment.

Note: This example does not include the code page translation statements described above.

Microsoft Windows XP [Version 5.1.2600]

(C) Copyright 1985-2001 Microsoft Corp.C:\Documents and Settings\pegauser>d:D:\>cd \zSeries\coreDistributionImageD:\zSeries\coreDistributionImage>ftpftp> open zosConnected to zos18.rpega.com.220-FTPD1 IBM FTP CS V1R8 at ZOS18, 13:15:30 on 2010-08-18.220 Connection will close if idle for more than 5 minutes.User (zos18.rpega.com:(none)): pegauser331 Send password please.Password:230 PEGAUSER is logged on. Working directory is "PEGAUSER.".ftp> ascii200 Representation type is Ascii NonPrintftp> cd "'PEGA.DB2.CNTL'"250 The working directory "PEGA.DB2.CNTL" is a partitioned data setftp> lcd .\schema\db2zos\libraries\PEGA.DB2.CNTLLocal directory nowD:\zSeries\coreDistributionImage\schema\db2zos\libraries\PEGA.DB2.CNTL.ftp> promptInteractive mode Off .ftp> mput *

21


200 Port request OK.125 Storing data set PEGA.DB2.CNTL(PC00REN)250 Transfer completed successfully.ftp: 957 bytes sent in 0.00Seconds 957000.00Kbytes/sec.200 Port request OK.125 Storing data set PEGA.DB2.CNTL(PC01CDB)250 Transfer completed successfully.ftp: 603 bytes sent in 0.00Seconds 603000.00Kbytes/sec.200 Port request OK.125 Storing data set PEGA.DB2.CNTL(PX01SPDD)250 Transfer completed successfully.ftp: 633 bytes sent in 0.00Seconds 633000.00Kbytes/sec.200 Port request OK.125 Storing data set PEGA.DB2.CNTL(RXCHGDSN)250 Transfer completed successfully.ftp: 2847 bytes sent in 0.00Seconds 2847000.00Kbytes/sec.ftp> bye221 Quit command received. Goodbye.D:\zSeries\coreDistributionImage>

5. Set parameters in the PARMLIB libraryTo specify the parameters for your Process Commander JCL jobs, you make copies of thePEGPROPS and USERENVmembers of the PEGA.DB2.PARMLIB library and edit them toprovide the necessary information.

1. Open the Pega PARMLIB library (PEGA.DB2.PARMLIB or your equivalent dataset name)for editing.

Edit the PEGPROPS member

2. Copy the PEGPROPSmember to the 8 character database name that is going to be usedfor Process Commander.

Making a copy that is specific to this database allows you to make other copies of theproperties file in the library to support other Process Commander databases. You specifywhich properties file to use for a particular user in the USERENV member described below.

3. Review each line in this renamed property member making the appropriate changes to thevalues to reflect your environment. These properties correspond to the values you collectedabove in Collect Parameter Settings for Your Environment on page 10.

4. Add a WLM parameter, #UDFWLM, to the PEGPROPS member.

Add the following line to the PEGPROPS file:

#UDFWLM = wlm application environment name

22


Specify the Work Load Manager application environment name for the dedicatedWLM you configured to support the PRPC User Defined Functions.

See, To support User Defined Functions (UDF) installed by PRPC on page 8

Edit the USERENV member

5. Copy the USERENV member to the name of the TSO/Database Owner userid that is going tobe used to create the database by running the Create JCL jobs. See Identify z/OS User IDson page 10.

Making a copy of the USERENV using the TSO/Database Owner userid allows you specifydifferent sets of properties for different users.

6. Review each line in this renamed property member making the appropriate changes to thevalues to reflect your environment, as shown in the table below. Work with your DBA andData security team, to identify your selections for each of the following variables, andmodify the PEGPROPS member as needed.

Note: The default values listed here, for example, for primary and secondary space allocations,have been tested by Pegasystems and will support the initial installation and validation of a PRPCsystem. As your unique requirements, and use case, evolve, some of these values may change.

Variable with Default Description

Pega Base Install Libraries

PEGAJCL=PEGA.DB2.CNTLPega Control library containing the JCL that is used forcreating a DB2 database for Pega installation. If you haverenamed the library from the default, provide the name here.

PEGAPRC=PEGA.DB2.PROCLIB

Pega Procedure library containing the procedures executedby the JCL in the Pega Control library to create a DB2 databasefor installing Pega Rules. If you have renamed the library fromthe default, provide the name here.

PEGADDL=PEGA.DB2.DDL

Pega Database Definition Library containingmembers thatcontrol the execution of DB2 utilities for creating a DB2 databasefor Pega installation. If you have renamed the library from thedefault, provide the name here.

PEGAPRM=PEGA.DB2.PARMLIB

Pega Parameter library containingmembers, (DBPROPS, PEGPROPS,USERENV, and UPGFILES) in which you enter site specific informationneeded to create a DB2 database for a Process Commander instal-lation.If you have renamed the library from the default, provide the namehere.

Pega Product Install Libraries

PEGPFX=PEG Pega prefix. If you have renamed the jobs in the Process Commanderlibraries using the PC00REN job, specify the prefix you used.

23



PRDDDL=PEGA.product.DDL

The name of the library you allocated for the Process Commander DDL(Database Definition Language)members --SQL definitions to createall the product’s database components except the stored procedures.By default for this release, the suggested library name isPEGA.PEG63.DDL You create this library by moving the contents ofschema/db2zos/EBCDIC/install or schema/db2zos/UNICODE/install,depending on the format of your database, to the library you allocate inyour z/OS environment.See 4. Move the library files from the distribution to the mainframe onpage 18.

PRDSRC=PEGA.product.SOURCE

The name of the library you allocated for the library members thatcontain the source necessary to create all the product’s databasestored procedures. By default, the suggested library name for thisrelease is PEGA.PEG63.SOURCE.

You create this library by moving the contents ofschema/db2zos/EBCDIC/install/source orschema/db2zos/UNICODE/install/source,depending on the format of your database, to the libraryyou allocate in your z/OS environment.See 4. Move the library files from the distribution to the mainframe onpage 18

Pega Product Upgrade Libraries

UPGDDL=PEGA.product.DDL

The name of the library you allocated for the Process Commander DDL(Database Definition Language)members --SQL definitions to createall the product’s database components except the stored procedures.By default for this release, the suggested library name isPEGA.PEG63UPG.DDL.

UPGSRC=PEGA.product.SOURCE

The name of the library you allocated for the library members thatcontain the source necessary to upgrade all the product’s databasestored procedures. By default, the suggested library name for thisreleaseis PEGA.PEG63UPG.SOURCE.

DB2 libraries required for Process Commander install

PROPNAME=property-name

Member name of the property file for this database in thePEGA.DB2.PARMLIB.This is the name you used for your copy of the PEGPROPSmember.Usually it is the 8 character name of the Process Commander data-base.

DB2SSID=DB9G The DB2 sub-system ID in which the Process Commander databasewill be defined.

DB2VER=910 Version of the z/OS DB2 system.

DB2HLQ=DSN910 High level qualifier of the z/OS DB2 system library datasets.

24



SDSNEXIT=SDSNEXIT Together with the DB2HLQ value, identifies the z/OS DB2 EXITlibrary name.

SDSNLOAD=SDSNLOAD Together with the DB2HLQ value, identifies the z/OS DB2 LOADlibrary name.

SDSNSAMP=SDSNSAMP Together with the DB2HLQ value, identifies the z/OS DB2 SAMPLElibrary name.

SDSNPROC=PROCLIB Together with the DB2HLQ value, identifies the z/OS DB2PROCLIB library name.

SDSNRLIB=RUNLIB.LOAD Together with the DB2HLQ value, identifies the z/OS DB2 RuntimeLOAD library name.

SDSNCHDR=SDSNC.H Together with the DB2HLQ value, identifies the z/OS DB2 LPPC Header library name.

DB2 libraries required to install and then run Pega DB2 Stored ProceduresIn the following, replace hlqwith your High-Level-Qualifier andmlqwith your Middle-Level-Qualifier.

DB2CSRC=hlq.mlq.CSRC Identifies the library to be used for the generated C Source modules.

DB2DBRM=hlq.mlq.DBRM Identifies the library to be used for the databaseresource modules (DBRM).

DB2LOAD=hlq.mlq.LOAD Identifies the library to be used as the load library for the Pega ExternalStored Procedures.

PROCNM=wlm-proc-nameName of the WLM procedure under which the Process Commanderexternalstored procedures will be run.

YOURPROC=customers-user-proclib Name of your system PROCLIB in which to store the WLM procedure.

Editing the DBPROPS member

The DBPROPS member specifies the JDBC parameters needed to establish a database connectionto your existing Pega Database. Remember that the Database user and password that you supplyneeds the authority to create and drop database objects.

In this member you set the following parameters:

dbURLThe JDBC connection URL for your Process Commander database.

user and passwordThe username and password for a database user having access to your Process Commanderdatabase. This user must have permissions to modify the database.

currentSchema and currentSQLIDThe name of the schema on your Process Commander database. usually this default to the

25


user name.

currentFunctionPathSupply the DB_Schema name as the final parameter. Do not modify SYSIBM or SYSFUNC

Leave the other values at their defaults.

6. Verify the environmentIn the PEGA.DB2.CNTL library, run the following verify jobs to confirm that the environmentvalues are setup correctly. All these jobs should return a condition code of zero.

1. PV01INST

Runs the Pega install script in batch. It verifies that the Pega Install procedure whichexecutes the Pega data parser and the IBM DB2 module SPUFI (SQL Processing Using FileInput) to process the parser data run successfully.

2. PV02UTIL

Runs the DB2 utility function. It verifies that the IBM DB2 utilities module runs successfully.

3. PV03SPUF

Runs your computer’s DB2 SPUFI in batch. It verifies that the IBM DB2 module SPUFI (SQLProcessing Using File Input) runs successfully.

7. Create the Database SchemaComplete the following steps to create the schema, tables, stored procedures and triggers in yourProcess Commander database, to support the 6.3 Rulebase. You can either run the procedures tocreate the schema on your z/OS system or on an external Windows, Linux, or Unix computer:

To run the procedure to create the schema on z/OS, continue below.

To run the procedure to create the schema from a Windows, Linux, or Unix computer, go to Tocreate the database schema from Windows. Linux, or Unix on page 30.

To create the database schema from z/OSTo create the schema, tables, stored procedures and triggers on z/OS, you run a sequence of jobsin the PEGA.DB2.CNTL library. You can create the database with native stored procedures, locatedin the database, or external stored procedures, located outside the database. Both procedures areoutlined below.

To create the database using native stored procedures

Run the following jobs in sequence.

26


Note: These JCL jobs call SPUFI to apply SQL in batch TSO. If you are installing toUNICODE database, you must be sure that the appropriate code page translation is configured inyour SPFUI environment.

1. PC00REN(Run only if you change the dataset names from the default prefix Pega.DB2.*)

This job dynamically renames the z/OS datasets PEGA.DB2.PROCLIB andPEGA.DB2.PARMLIB in all members of the Pega JCL library PEGA.DB2.CNTL. Use thismember to set the dataset names to match your site’s standards.

Before running this job, specify the names to use by editing the following parameter cardsin PC00REN to the names that were allocated for the Pega libraries:

PEGA.DB2.PROCLIB = customer.PROCLIB

PEGA.DB2.PARMLIB = customer.PARMLIB

2. PC01CDBCreate the database

Creates the DB2 database definition that will be used for the Process Commander system.

3. PC07BPTBuild Plan Table for Stored Procedures

Creates the bind plan tables for the external stored procedures that are used by the ProcessCommander Rules system.

4. PC02NDBBuilds all the Pega database structures in DB2 for a database that uses native storedprocedures, including:

– table spaces

– tables

– LOB table spaces

– LOBs, indexes

– views

– triggers

– native stored procedures.

5. PC13UDF

27


Create Pega's user defined functions.

This job loads the JAR file containing the functions to the DB2 catalog.

Before running this job, set the following parameters in the file:

SETOWNR SET DB2OWNR=PAIA1DBOSpecify the DBOWNR user.

SETJSDN SET JARDSN='/tmp/prreadstream.jar'Replace '/tmp/prreadstream.jar' with a ZFS location that can be used as temporary storagefor the JAR file when it is being loaded to the database.

SETJFTP SET PEGUDF=<DSN of the prreadstream.jar as a MVS VB file>Specify the library to which you tranferred the prreadstream.jar file above, e.g.,PEGA.PEG63.UDFJAR See page 19.

To create the database using external stored procedures

Note: You must configure a Work Load Manager to support external stored procedures. See theconfiguration information on page 8.

Run the following jobs in sequence.

1. PC00REN(Run only if you change the dataset names from the default prefix Pega.DB2*).

Dynamically renames the z/OS datasets PEGA.DB2.PROCLIB and PEGA.DB2.PARMLIB in allmembers of the Pega JCL library PEGA.DB2.CNTL. Use this member to set the datasetnames to match your site’s standards.

Before running this job, specify the names to use by editing the following parameter cardsin PC00REN to the names that were allocated for the Pega libraries:

PEGA.DB2.PROCLIB = customer.PROCLIBPEGA.DB2.PARMLIB = customer.PARMLIB

2. PC02BDBBuild database by defining its base components

Creates the DB2 database defnition that will be used for the Process Commander Rulebase.

3. PC05ALC

Allocates the three libraries required to create and run the DB2 database external storedprocedures used by the Process Commander system: CSRC, DBRM, and LOAD. You specify

28


the libraries dataset names in the USERENV member of the Process Commander systemPARMLIB library, by default PEGA.DB2.PARMLIB.

4. PC06GSPGenerate Stored Procedures auto submits PC06CSP Create Stored Procedures.

Generates the JCL to compile, link and create external stored procedures used by theProcess Commander system, and submits the JCL to build the stored procedures on behalfof the user as job PC06SP from PROCLIB.

5. PC07BPTBuild Plan Table for Stored Procedures

Creates the bind plan tables for the external stored procedures that are used by the ProcessCommander Rules system.

6. PC08RNSRun Stats

Runs the DB2 utility, RUNSTATS, to update the database statistics used for determiningaccess paths to the database.

7. PC09BNDBind Stored Procedure to Plan Tables

Binds all Process Commander external stored procedures to the plan tables that weredefined in job PC07BPT.

8. PC10TRGCreate database triggers

Defines all triggers used by the Process Commander system to the DB2 database definition.

9. PC11GRTIssue grants for tables, stored procedures and database.

Grants permissions for the Process Commander tables, stored procedures and the storedprocedure collection package to the user ids created to access the DB2 database. Youspecify these user ids in the DBPROPS member of the Pega system PARMLIB library, bydefault PEGA.DB2.PARMLIB.

10. PC12CPYCopy Work Load Manager procedure to customer’s user system PROCLIB.

29


Copies the work load manager (WLM) procedure that defines the WLM application used torun and control the Pega external stored procedures from the Pega PROCLIB library to theuser’s system PROCLIB.

11. PC13UDFCreate Pega's user defined functions.

This job loads the JAR file containing the functions to the DB2 catalog.

Before running this job, set the following parameters in the file:

SETOWNR SET DB2OWNR=PAIA1DBOSpecify the DBOWNR user.

SETJSDN SET JARDSN='/tmp/prreadstream.jar'Replace '/tmp/prreadstream.jar' with a ZFS location that can be used as temporary storagefor the JAR file when it is being loaded to the database.

SETJFTP SET PEGUDF=<DSN of the prreadstream.jar as a MVS VB file>Specify the library to which you tranferred the prreadstream.jar file above, e.g.,PEGA.PEG63.UDFJAR See page 19.

Refresh WLM Policy

After completing PC13UDFto load the PRPC UDF, be sure to refresh the WLM applicationenvironment specified for these functions. See 5. Set parameters in the PARMLIB library on page22

To create the database schema from Windows. Linux, or Unix

1. In the scripts/config/db2zos directory of your Process Commander softwaredistribution, open the file DB2Connection.properties in a text editor and enter theconnection settings for your PRPC database:

Property Value

dbURL=jdbc:db2://<DB_Server>:<port>/<DB_SubsystemID>

Enter the JDBC connection URL for your ProcessCommander database.

user=<DB_UserID>password=<DB_Password>

Enter the database user name and password youcreated for the Process Commander database.

currentSchema=<DB_Schema>Enter the schema name assigned to the ProcessCommander database when it was created. Theusername is used for the default schema name.

currentSQLID=<DB_Schema>

30


Property Value

currentFunctionPath=SYSIBM,SYSFUNC,<DB_Schema>

.

2. In the scripts/config/db2zos directory of your Process Commander softwaredistribution, open the file DB2SiteDependent.properties in a text editor and edit it toreflect the settings used on your zOS system.

For information on modifying this file, see 5. Set parameters in the PARMLIB library onpage 22.

Save and close the file.

3. Again in the config/db2zos directory, open the file SQLCommandFile.list in a texteditor.

This file lists the files containing the SQL commands to use to create your databaseschema. You can either supply the full path to each file, or you can list only the name or apartial path and supply the base path to be applied to each listing in the ARG5=-r setting inthe zOSSchemaLoader script file.

Modify this file as follows:

If you did not specify a base path as the ARG5=-r setting in thezOSSchemaLoader script file, replace%STMT_PATH% with the full path tothe files, as in the example in the file.

If you specified a base path , it will be used as the%STMT_PATH% variable inthis file.

Comment out the line%STMT_PATH%\PEGBND

.#%STMT_PATH%\PEGBND


Note: If you are using external stored procedures, you must install the 6.3 stored proceduresfollowing the instructions in the Installation Guide for 6.3. You must FTP the source and librarymembers to your z/OS system and install the stored procedures as described in “To create thedatabase using external stored procedures.”

4. In the scripts directory of your Process Commander software distribution, open thezOSSchemaLoader.bat script in a text editor.

31


5. Modify the zOSSchemaLoader script file to set the arguments to reference these files andcomplete the other arguments, as follows:

Set ARG1=-d to the full path to DB2Connection.properties.

If you have not moved this file from its default location, you can leave thisargument unchanged.

Set ARG2=-p the full path to DB2SiteDependent.properties.


Set ARG3=-c the full path to SQLCommandFile.list.


Set ARG4=-l to the location to which you want to write the log file generated bythis script.

Set ARG5=-r to the base path of the z/OS libraries in the Process Commanderdistribution, for exampleARG5=-r D:\63_0051\schema\db2zos\libraries

Set DB2DriverPath to the full path to the location of the z/OS DB2 databasedrivers on your local system.


6. Run the zOSSchemaLoader script.

When the script has completed, you are ready to run PRPC-Setup.jar and upgrade the rules asdescribed in Steps 4-9: Rulebase Setup on page 1.

Start Work Load ManagerDefine and start a Work Load Manager (WLM) application that uses the WLM procedure copied inPC12CPY. You may need to consult your System Programmer about this step.

Next StepsYou can continue either with Step 3, Application Server Configuration, or Steps 4-9, Rulebase Setup.These two procedures are independent and can be completed in either order or simultaneously.

32


Note, however, that you cannot run Process Commander successfully until the database setup iscomplete. If you deploy and start the Process Commander application before the database is complete,the application generates errors.

Important: You must be careful not to start the deployed Process Commander applications while the Rulebaseloading process is still running on the database. Note that your application server may start the applicationautomatically when it is deployed. If the Process Commander application attempts to connect to the databasewhile the Rulebase is loading, the database loading will not complete correctly.

33


Step 3: Application Server PreparationThis chapter describes the tasks you must complete to configure your application server and deploy theProcess Commander Java EE applications.

Before deploying the PRPC applications, you:

Verify the Java Environment

Configure Support for the Process Commander Database on Your Server

Create a WebSphere Profile

Configure the Application Server

To deploy the Process Commander system, you deploy three applications:

the Process Commander core application, prweb.war or prpc_j2ee14.ear

the System Management Application, prsysmgmt.war or prsysmgmt.ear

the Developer Help application, prhelp.war.

Verify the Java EnvironmentConfirm that the Java JDK environment used by your application server is a Java 5 JDK of 1.5.0_07 orhigher, or a Java 6 JDK. The Java 7 JDK is not yet supported for Process Commander 6.3

Be sure your application server is configured to use an appropriate JDK. The default Java environmentfor your application server may not be one of the recommended JDKs for Process Commander.

Important: During installation, Process Commander requires access to the directory specified by thejava.io.tmpdir setting in the JVM. Confirm that there is write access to this directory before installingProcess Commander.

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.

Configure Support for the Process Commander DatabaseIn order to support JDBC connections between your application server and the Process Commander, youmust install the appropriate database client software and JDBC drivers on your application server asrecommended by your database vendor.

Follow the IBM instructions for installing the client software and the JDBC drivers to make thedb2jcc.jar available.

This JDBC driver is the Type 4 universal driver.

34


Configure the application server so that this driver is loaded in the classpath.

Create a WebSphere ProfileRun the WebSphere Profile Management Tool to create a WebSphere Application Server profile in whichto run the PRPC application. You must create a new profile dedicated to PRPC, so that PRPC can run in itsown JVM environment.

You may use either the Typical profile creation or the Advanced profile creation option. The Typicalprofile assigns default values for such things as the Profile name, Node name, Host name, and accessports. Advanced Profile creation lets you change the defaults. Both methods allow you to choosewhether to apply Administrative Security requiring a login with user name and password when startingthe Administrative Console.

If you choose the Advanced option, be sure to choose to deploy the Administrative Console.

Note: On Windows platforms, the Typical option creates the application server as a Windows service bydefault. This means that you must manage the profile as a Windows service, for example when startingand stopping the server.

If you do not want to run the application as a Windows service, choose the Advanced profile creationoption and, on the Windows Service Definition page, do not check “Run the application server process asa Windows Service.”

Make sure you record the following information about the profile you create:

Profile name

User name and password for the Administrative Console (if you choose to apply AdministrativeSecurity.)

Port numbers for the profile, including at least:

– Administrative Console Port (9060 by default)

– HTTP transport port (9080 by default)

Depending on your environment, you may also need to record the port numbers for the Administrativeconsole secure port, the HTTPS transport port, and the SOAP connector port. If you are unsure aboutthese requirements, check with your application server administrator

35


Start and Configure the Application Server1. Start the server for the new profile, launch the Administrative Console, and login.

On Windows platforms, you can start the profile server and launch the AdministrativeConsole from the Start menu, for example, in a default installation:

– To start the server, click Start > All Programs > IBM WebSphere > Application Serverv7.0 > Profiles > AppSvr01 > Start the server.

– To launch the Administrative Console, click Start > All Programs > IBM WebSphere >Application Server v7.0 > Profiles > AppSvr01 > Administrative Console.

If you enabled Administrative Security when you created the profile for this server, you willneed to login using the user name and password you specified at that time.

When the Administrative Console is launched, it displays the Welcome screen forWebSphere’s Integrated Solution Console:

2. Click the link WebSphere Application Server to display the Welcome page for the

36


Application Server:

Set JVM Requirements

Setting Memory Parameters

Set these memory parameters as described below:

Initial Heap Size: 1024

Maximum Heap Size: 2048

If your application server is using the Sun JVM, add the PermSize and MaxPermSize settings aswell:

PermSize: 64

MaxPermSize: 384

Follow these steps to set these parameters.

1. 1. In the Administrative window, on the left side of the screen, click Servers > ServerTypes > Websphere application servers.

37


2. Find the name of the server on which Process Commander will run, and click that servername. (In the example above, the server is server1.) The Configuration tab for that serverappears.

38


39


3. In the Server Infrastructure section, click the “+” next to Java and ProcessManagement to expand the section, then click Process Definition.

You may need to scroll down in the window to see the Server Infrastructure section.

This displays the Configuration tab for Process Definition.

4. In the Additional Properties section, click Java Virtual Machine. This displays the

40


Configuration tab for the Java Virtual Machine.

41


5. On this window set:

- Initial Heap Size to 1024

42


- Maximum Heap Size to at least 2048

Note: These values are initial minimum estimates for typical development systems. They may needto be higher based on your server hardware and the number of other applications on the server.Consult with your System Administrator about the requirements for your site.

6. If your WebSphere instance is using the Sun JVM, in the Generic JVM Arguments fieldset a PermSize of 64MB and a MaxPermSize of 384MB by entering:

-XX:PermSize=64m -XX:MaxPermSize=256m

Separate the JVM Arguments with a space . Do not use commas.

Note: These settings are minimum settings only. They may need to be higher based on your serverhardware and the number of other applications on the server.

7. Click Apply. A message appears at the top of the screen explaining that the changes weremade.

8. Click Save to save these changes to the master configuration.

Enable AWT to support PRPC Graphs

This setting enables the server to render graphics used by the PRPC graphical reports.

1. From the Application Servers > server1 > Process Definition page, underAdditional Properties, select Java Virtual Machine to return to the Configuration page.

2. In the Generic JVM Arguments field, enter the following system property JVM argument:

-Djava.awt.headless=true

For example,

43


Note: Separate this argument from any others in the field with a space. Do not use commas.

3. Click Apply.

4. In the Messages section at the top of the page, click Save.

Create URL ProvidersFollow the procedure below to set the required URL Pega reference and an explicit Temporary directoryfor Process Commander. The temporary directory is used by Process Commander to store static data. Itis important that the directory be properly specified and accessible to the Process Commander user. InWebSphere you specify this directory as a JNDI reference to a URL object.

1. In the WebSphere Administration console select Resources > URL > URL Providers inthe left frame.

2. Set the Scope level appropriate to your deployment, and click on the Default URLProvider link. In the following example, the scope is set to the server level.

44


3. Under the Additional Properties section, click on the URLs link to display the URLs listingpage:

45


4. Click New to display the Configuration page:

46


5. Define a URL for the NULL file that Process Commander can use to discard erroneouserrormessages Complete this form as follows:

– In the Name field, enter PRPCnone

– In the JNDI name field, enter url/pega/none

– In the Specification field, enter file:///nul for Windows or file:///dev/null forUNIX/Linux.

6. Click OK and then Save in the confirmation message.

7. From the URLs page, click New again to return to the Configuration page.

8. Complete this form to create a URL specification for a temporary directory that ProcessCommander can use to store static data:

– In the Name field, enter PegaTempDir

– In the JNDI field, enter url/initialization/explicittempdir

– In the specification field, enter file:/// followed by the full path to the temporarydirectory. Enter the path using forward slashes for both Windows and UNIX platforms. Forexample, on Windows the value might be: file:///D:/Temp/PegaTempDir.

47


Important: The directory names you enter here are case sensitive. Be sure to enter the names ofthe directories exactly as they have been created on your system.

Notes: If the directory you specify does not exist, Process Commander will attempt to allocate it. Itis good practice to allocate the directory on the system before specifying it here.

The user that owns the Java process must have the appropriate permissions to use this directory,including write access. In particular, if you have J2 security enabled, ensure that this directory isaccessible under your security policy.

In a clustered deployment, each Process Commander instance must have its own temporarydirectory. You cannot share a temporary directory with more than one Process Commanderinstance.

9. Click OK and then Save in the confirmation message.

48


Create JDBC ResourcesCreate a JDBC provider

1. In the Administrative console, click Resources > JDBC > JDBC Providers to display theJDBC Providers page:

2. In the Scopes dropdown, choose the scope level appropriate to your deployment, and clickNew to display the JDBC provider wizard:

49


Note: The screen shots in this section show the settings for an Oracle database. If you are not usingOracle, follow the instructions for each step to configure the JDBC provider for your database,replacing the Oracle settings shown in the screen shots with the appropriate information for yourdatabase.

3. Complete the fields in Step 1 as follows:

– In the Database type dropdown,select .

– In the Provider type dropdown, choose .

– In the Implementation type dropdown, select Connection pool data source.

– In the Name and Description fields, accept the defaults or enter a descriptive nameand explanatory description for the driver you selected.

Click Next to display Step 2:

50


4. In the Directory location field, confirm the entry, if one is displayed, or enter the path tothe driver class file or files listed in the Class path field.

Note: Be sure only the appropriate JAR file is loaded. Do not put both sqljdbc.jar and sqljdbc4.jar inthe classpath.

Click Next to display Step 3.

5. Confirm that the settings are correct, and click Finish.

51


You are returned to the JDBC Providers page.

6. Click Save in the confirmation message.

Create Data Source

1. Still on the JDBC providers page, click on the name of the provider you just created todisplay the General Properties page.

52


2. Under the Additional Properties heading, click Data Sources.

53


10. Click New to display the data source wizard:

54


55


3. Click New to display the data source wizard:

– In the Data Source name field, enter PegaRULES

– In the JNDI name field, enter jdbc/PegaRULES.

– Click Next to display Step 2:

56


4. Supply information about your Process Commander database.

If you are unsure about the information to supply for your database server, consult withyour site DBA.

Click Next to display Step 3:

57


5. Click Next to display the Summary page. (You will supply DB credentials in a later step):

58


6. On the Summary page, confirm that the settings are correct and click Finish.

You are returned to the JDBC Providers page.

59


7. Click Save in the confirmation message.

8. Still on the Data Sources page, click the PegaRULES link in the Name column to open theConfiguration page for this data source. Then, under Additional Properties, click on theCustom Properties link to display the Custom Properties page:

60


9. Click New to define any additional properties you may need for your database connectionhere.

61


To create a new property, click New on the Custom Properties form. After creating eachproperty, click OK to save the property, and New again to create the next property. Besure to set the Type field appropriately for the Value of the connection property.

10. After you have set the necessary properties, click the Save link in the message at the topof the page.

Define Database Authentication Credentials

1. In the link path at the top of the page, click PegaRULES to return to the PegaRulesproperties page. Then, under the Related Items section, click the link JAAS – J2Cauthentication data. You will define your database authentication credentials here.

62


2. Click New to specify the General Properties.

3. Complete this form as follows:

– In the Alias field enter any name that uniquely identifies this J2C entry.

– In the User ID and Password fields, enter the user name and password for the PRPCdatabase user on your Process Commander database.

4. Click OK to return to the authentication data entries page, and click Save in the Messagessection at the top of the page.

5. In the link path at the top of the page, again click PegaRULES to return to the PegaRulesproperties page.

63


6. In the Security Settings section near the bottom of the page, use the Component-managed authentication alias dropdown to select the J2C alias you just created:

64


7. Click Ok, and then Save in the confirmation message on the Data sources page.

8. On the Data sources page,select the checkbox for PegaRULES and click Test Connectionto confirm your data source configuration.

Configure WebSphere WorkManagerIf you are deploying Process Commander’s EAR archive, prpc_j2ee14_ws.ear, complete the followingprocedures to define a WorkManager. Process Commander uses the WorkManager to run asynchronoustasks to support internal components such as agents, services, daemons, and child-requestors.

If you are deploying Process Commander’s WAR archive, prweb.war, you do not need to configure theWorkManger. Continue with the configuration procedure, “Other WebSphere Configuration” on page 46.

Complete the following procedures to define the WorkManager:

1. In the navigation menus on the left of the Administration Console, expand Resources,expand Asynchronous Beans, and selectWork Managers

65


2. On the Work Managers listing page, set the Scope to the level appropriate for yourdeployment, and click New.

66


3. Complete the Configuration page for the Work Manager as follows:

– In the Name field, enter a name to identify this Work Manager, for example,PRPCWorkManager.

67


– In the JNDI name field, enter exactly the JNDI locationwm/PegaWorkManager

– In the Service names section, select the Security checkbox.

– In Thread pool properties, setMaximum number of threads to 5.

– Uncheck the Growable checkbox.

4. Click OK.

You are returned to the Work Managers listing page.

5. In the Messages box at the top of the page, click Save.

Set HTTP transport channel custom property CookiesConfigureNoCache tofalse

In order to support the ability to open files attached to work objects in Process Commander, you mustset a custom property, CookiesConfigureNoCache, on the transport chain in the Web Container settingsfor the Process Commander server.

Note: In earlier versions of WebSphere, this property was set to false so that cookies could be cached by default.Process Commander requires this caching to allow users to open attached files directly from a work object. InWebSphere 7.0, this property is set to True by default so that caching is not allowed. You must create and set thisproperty on the HTTP transport channel for the Process Commander server.

Complete the following steps to set this property.

1. In the administrative console, select Servers > Server Types > WebSphereapplication servers to display the Application servers page.

2. Click on the name of your Process Commander server to display the Configuration page:

68


3. Under Container Settings, expandWeb Container Settings, and then clickWebContainer transport chains.

This console displays the listing page for transport chains

69


4. Click the name of the appropriate transport chain:

– If your site is using the default transport configuration for this server, selectWCInboundDefault or, if you have enabled SSL for the Process Commander port,WCInboundDefaultSecure.

– If your site has defined a custom transport chain for this server, select that chain name

The console displays the Configuration page for the selected transport chain.

70


5. Under Transport Channels on this page, click HTTP inbound channel.

The console displays the Configuration page for the selected transport channel.

71


6. Under Additional Properties on this page, click Custom Properties.

The console displays the listing page for this channel’s custom properties

72


7. Click New

The console displays the form for a new custom property

8. Complete this form as follows

– In the Name field, enter CookiesConfigureNoCache

– In the Value field, enter False.

9. Click OK, and then Save in the Messages box on the Custom Properties listing page

Deploy the PegaRULES core applicationComplete the instructions below to deploy the PRPC core application component prpc_j2ee14_ws.ear.

Important: The PRPC core application component is available both as aWAR file, prweb.war, or an EAR file, prpc_j2ee14_ws.ear. Pegasystems recommends deploying the EAR file component, prpc_j2ee14_ws.ear for all newdeployments on WebSphere 7.0 systems. The WAR file core component, prweb.war, can be successfully deployedon the WebSphere application servers, but deploying and configuring the EAR file ensures that you can addadvanced J2EE features as your application grows or when you migrate to a production environment.

Do not install both prweb.war and prpc_j2ee14_ws.ear.

73


Note:WebSphere automatically starts the application, prweb.war or prpc_j2ee14_ws.ear, when it is deployed.When the application starts up, you may see error messages for missing resources and references. You may ignorethese messages. You will supply these resources as you complete the installation process. Be sure to stop theapplication after deploying.

Deploying prpc_j2ee14_ws.ear in WebSphere

1. Ensure that the WebSphere Application Server is running, and log into the administrationconsole

2. Under the left frame, select Applications > New Application

3. Click New Enterprise Application.

74


4. Click the Browse button and navigate to select prpc_j2ee14_ws.ear from your installationmedia. Click Next.

WebSphere displays Preparing for the application installation

5. Click the radio button: Detailed - Show me all installation options and parameters

This option will allow you to review all the installation options for the application, includingthe default bindings and resource mappings

6. Click the ‘ + ‘ sign to expand Choose to generate default bindings and mappings

75


7. Complete this page as follows

– Check Generate Default Bindings

– Check Use default virtual host name for Web and SIP modules.

– Accept the other defaults and click Next:

WebSphere displays the following Security Warning

76


8. Scroll to the bottom on this page and click Continue

This security file allows Process Commander to run when J2EE Security Checking isenabled.

WebSphere displays a wizard in which you can specify installation options

77


78


This section of the installation process is a series of steps under the general heading ofInstall New Application. For Process Commander, you only need to make changes inStep 10, Map resource references to resources. For each of the other screens, youmay accept the defaults, or customize them according to the requirements of yourorganization.

9. For Step One, accept the defaults and click Next

10. Continue through the next steps, either accepting the defaults, or customizing for yourorganization, as needed.

– In Step 10, you map resource references to resources

79


80


11. For the three Resource references to url/initialization/explicittempdir, enter the JNDIname url/initialization/explicittempdir in the field Target Resource JNDI Name.

There are url/initialization/explicittempdir references for the EJB EngineCMT, EngineBMTand prweb.war.

This maps the location you specified in the URL provider you created above to thecorresponding Resource Reference in the application, so that the application will use thelocation for the PegaTempDir.

12. Click Next

Depending on your configuration, you may see a set of warnings related to missingresource references, for example:

These are resource references that are defined in web.xml, the deployment configurationfiles for the application, but not mapped to resource definitions in your application. In thepage, Map resources to references, they are mapped to the Target Resource JNDI Nameurl/pega/none, indicating that they are not used. Pegasystems provides these referencesfor J2EE compliance, but their use is optional. You can continue with the deployment.

13. At the bottom of the Warnings page, click Continue.

14. Continue through the remaining steps, accepting the defaults, or setting them to therequirements of your organization.

81


15. The system begins installing the EAR file, which may take a few minutes. The followingmessage is displayed.

82


When the installation completes successfully, WebSphere displays a message similar to thefollowing:

16. Click Save directly to the master configuration.

Installing the System Management and Online Help ApplicationsIn addition to the Process Commander application, you must also deploy the online help application(prhelp.war) and System Management application (prsysmgmt.war).

For more details on the System Management Application, refer to the System Management ApplicationReference Guide available on the Pega Developer Network (pdn.pega.com).

Complete the following steps to deploy prsysmgmt.war or prsysgmgt.ear.

83


1. Under the left frame, select Applications > New Application.

2. Click New Enterprise Application.

3. Click the Browse button and navigate to select the application war file, prsysmgmt.war orprsysgmgmt.ear, from your installation media.

4. Click Next to begin the installation:

84


5. Click the radio button: Detailed - Show all installation options and parameters.

6. Click the ‘ + ‘ sign to expand Choose to generate default bindings and mappings:

7. Select the Generate Default Bindings check box, and leave the other settings at theirdefaults.

8. Click Next.

85


You may see some security warnings similar to the following:

9. Click Continue to pass by the warnings.

WebSphere displays the Install New Application wizard:

86


10. Accept the defaults and click Next for Steps 1 through 7.

11. In Step 8, enter the name of the file, prsysmgmt or prhelp, as the context root, and clickNext.

87


12. On the Summary page, click Finish.

88


WebSphere displays a message, Installing . . ., and updates it with information during theinstall. When complete the following message is displayed in the page:

13. Click the Save link to save the changes to the master configuration.

89


You are returned to the first page of the installation series:

14. Deploy prhelp.war using the same procedure as prsysmgmt.war

Use the name of the file, prhelp, as the context root and deploy to the same server.

Assigning the PegaDiagnosticUser Role to your SystemManagement Application UsersUsers accessing the System Management Application (SMA) in Process Commander must be assignedthe role PegaDiagnosticUser. Users can access the SMA in the Process Commander Developer portal byclicking Tools > System Management Application. If the user does not have this role they will bechallenged for authentication when they attempt to access the System Management Application fromProcess Commander.

You can use the SMA to monitor and control caches, agents, requestors, listeners, and other processingin the Process Commander system. For more information, consult the System Management ApplicationReference Guide available on the Pega Developer Network (pdn.pega.com).

Complete the following steps to set access to the System Management Application.

– If you want to allow limited access to the SMA, use the Map Special Subjects dropdown toselect All Authenticated in Application’s Realm, or click Map Users . . . to assign the role tospecific users.

90


1. Select Applications > Application Types > WebSphere enterprise applications.

2. Click the name of your Process Commander core application, for example prpc_j2ee14_ws,to open the Configuration page.

91


3. In the Detail Properties section, click Security role to user/group mapping.

If you installed the EAR archive, prpc_j2ee14_ws.ear, the PegaDiagnostic role is set toEveryone:

If you installed the WAR archive, prweb.war, the PegaDiagnosticUser role is set toNone:

4. Select PegaDiagnosticUser and set the proper access level for your site:

If you do not want to allow access to the SMA, use the Map Special Subjectsdropdown to select None.

If you want to allow limited access to the SMA, use the Map Special Subjectsdropdown to select All Authenticated in Application’s Realm, or click MapUsers . . . to assign the role to specific users.

92


If you want to allow open access to the SMA, use the Map Special Subjectsdropdown to select Everyone.

Next StepsIf you have not completed the Rulebase Loading phase, continue with the next section: Steps 4-9Rulebase Setup Phase. Be sure that the Process Commander applications you just deployed are notstarted.

If you have completed the Rulebase Loading phase, start the Process Commander applications andcontinue with Step 10, Final Settings in PRPC.

93


Steps 4 to 9 - Rulebase Setup

Install the Process Commander Schema and Rules in the DatabaseRun the Process Commander Installation and Upgrade Assistant to create the Process Commanderschema in the database, and load the Process Commander application rules.

Note: The following procedure describes the use of the user-interface to the installer to create the schema in thedatabase and load the base Process Commander rules. The 6.3 distribution also includes scripts to support thesetasks through a command-line interface. Support is provided through install.bat and install.ksh files configuredthrough a properties file, setupDatabase.properties. To use the scripted option, see the README.txt file in the"scripts" directory of your Process Commander software distribution.

The computer on which you run the Installation and Upgrade Assistant must have access to allow adatabase connection to the Process Commander database. This computer should also have at least

1GB of RAM

6GB of disk space available for the temporary directory, pegaGuiInstallerTemp, created inthe directory in which PRPC_Setup.jar is run. This directory is deleted when the assistant'sprocesses are complete.

a local installation of a Java 5 JDK of 1.5.0_07 or higher, or a Java 6 JDK. The Java 7 JDK is notyet supported with Process Commander 6.3.

Move the Process Commander Software Distribution to Your ComputerIf you are installing the software distribution downloaded from Pegasystems, copy the distributionfile, for example 113990_prpc63.zip, to the computer on which you will run the Installation andUpgrade Assistant. Extract the contents of the ZIP file to an empty directory.

If you are installing the software from the Process Commander DVD, copy the contents of the DVDto an empty directory.

Important: Be sure this computer has a high-speed network connection to your database. For best performance,run this Installation and Upgrade Assistant directly on the database server. The Rulebase Loading step in this toolloads several gigabytes of data to the database. Loading this data over a VPN or slow network connection candramatically increase the total time required to complete the process. If you cannot run the Assistant directly onthe database server, please run this tool on amachine with fast, direct network access to the database server.

The Process Commander home directory contains the following directories and files:

94


Update Java 6 JDK to JAX-WS API 2.2.5If you are using the Java 6 JDK, you must update the JDK environment to use version 2.2.5 or later ofthe JAX-WS API. The JAX-WS API (jaxws-api.jar) bundled with the Java 6 JDK is version 2.0. ProcessCommander requires at least JAX-WS version 2.2.5 to support its implementation of CMIS integrationand WS-Security.

Use the Java Endorsed Standards Override Mechanism(http://docs.oracle.com/javase/6/docs/technotes/guides/standards/) to ensure that the 2.2.5 classesare loaded:

1. In the expanded Process Commander software distribution, go toResourceKit/Utilities/Java6Updates.

2. From that directory, copy jaxws-api-2.2.5.jar and resolver.jarto the <JAVA_HOME>/lib/endorsed directory on your application server. Create the endorseddirectory in the lib directory if one does not exist.

When you restart your application server, the Java bootstrap loader loads the classes in the endorseddirectory in place of any it might find otherwise.

Rulebase Setup Using the Installation and Upgrade AssistantFollow these steps to load the Process Commander rules to the database.

95


1. Double-click on the PRPC_Setup.jar file or right-click the file and click Open With >Java, to launch the Installer.

If JAR files are not associated with Java commands on your system, launch the installer atthe command-line. In a command-line console, change to the directory containing PRPC_Setup.jar, and type in the following command:

Java –jar PRPC_Setup.jar

Note: Use the command-line jar command on Windows systems if you see the following error when you try tolaunch PRPC_Setup by double-clicking the JAR file.

Could not extract JAR file to directory: C:\Windows\System32\pegaGUIInstallerTemp

96


2. Click Next to display the Performance Considerations

Review these items to be sure that your system is prepared to allow the installation toperform efficiently. In particular, network connectivity and database maintenance issuescan significantly increase the time required to load the 6.3 Rulebase into your PRPCdatabase.

3. Click Next to display the Environment Considerations.

97


See Step 1, Environment Considerations in this guide for more information oncompleting this step.

4. Click Next to display the Database Preparation page.

98


Review this page to confirm that you have prepared the database as required.

See Step 2, Database Preparation in this guide for more information on completing thisstep.

These tasks are completed outside of the Assistant. You must complete this preparationbefore running the Rulebase Load phase. You can exit from this tool to complete them, andthen restart to continue beyond this point.

Important: Be sure you have configured the database user you will use during installationas described in Create Database Users on page 1. In particular, the database operatorused to connect to the database during the installation procedure must be explicitly grantedthe CREATE_EXTERNAL_ROUTINE privilege, for example:

GRANT CREATE_EXTERNAL_ROUTINE ON DATABASE TO USER <username>

5. When your Database Preparation is complete, click Next to display Application ServerPreparation.

99


6. Review this page to learn about the tasks you complete to prepare your application serverbefore deploying the Process Commander applications.

These tasks are completed outside this Assistant. You can exit from this tool to completethem, and then restart to continue beyond this point, or you can continue with the RulebaseSetup phase immediately and complete the Application Server Preparation later.

Note:When the Database Preparation is complete, Step 3, the Application Server Preparation, andSteps 4-9 in the Rulebase Setup Phase can be performed in either order or simultaneously. You can,for example, launch the Rulebase Setup process in the Assistant and then configure your ApplicationServer while the Rulebase load process is running.

However, you must configure the application server and deploy the Process Commander applicationsbefore you can complete Step 10, PRPC Final Settings.

Important: You must be careful not to start the deployed Process Commander applications whilethe Rulebase loading process is still running on the database. Note that your application server maystart the application automatically when it is deployed. If the Process Commander applicationattempts to connect to the database while the Rulebase is loading, the database loading will notcomplete correctly.

7. If you have completed your Application Server Preparation or you want to continue with the

100


Rulebase Setup in the database before completing the Application Server Preparation, clickNext to display the License Agreement.

8. Review the License agreement and click Accept to continue to Type of Setup.

101


9. Select Installation and click Next to display the Database Configuration page.

102


10. Complete this page as follows:

Database Type

– Select the type of your Process Commander database.

Create Database Schema

– Leave Create Database Schema checked to allow the Assistant to create theappropriate schema in the database as part of the Rulebase Load process. Youdatabase should be empty.

– Uncheck Create Database Schema if you used your database tools to create theschema using the SQL scripts provided in the schema directory of your softwaredistribution.

See “Using a SQL Script to Create the Schema” in this guide for more information.

Note: If you run the Assistant with Create Database Schema selected on a database that

103


Click Next to display the Database Connection page.

3. Complete the fields to specify the database connection to your Process Commanderdatabase:

JDBC Driver Class Name

Confirm the name of the appropriate database driver class: com.ibm.db2.jcc.DB2Driver

Driver JAR file

Enter the full path to the driver file.

Use additional fields if your database requires more than one JAR file.

See Configure Support for the Process Commander Database for information on yourdatabase.

104


Database JDBC URL

Enter the JDBC connection URL for your Process Commander database in the following format:

jdbc:db2://serverName:port/dbName

Username and Password

Enter the user name and password you created for the Process Commander user on yourdatabase.

Important: Be sure you have configured the database user you will use during installation asdescribed in Create Database Users on page 1. In particular, the database operator used toconnect to the database during the installation procedure must be explicitly granted theCREATE_EXTERNAL_ROUTINE privilege, for example:

GRANT CREATE_EXTERNAL_ROUTINE ON DATABASE TO USER <username>

Schema Name

Enter the schema name assigned to the Process Commander database when it was created.

UDF WLM Name

Enter the Work Load Manager Application Environment name that you configured forUDF support. See, To support User Defined Functions on page 8

4. When you have completed entering the database connection information, click TestConnection.

The Installation Assistant tests whether it is able to make a connection to the database youhave specified and displays the result:

Click OK to close the window.

105


If the connection is not successful, review your connection information, correct any errors,and retest.

When the connection is successful, click Next to continue to the System Name andProduction Level page.

5. If required, specify the System Name and Production Level to assign to the installedProcess Commander System. In most cases, the defaults are used.

Enter the full path to a directory or Browse to specify a temporary directory for theInstallation Assistant to use while loading the Process Commander rules. By default, theAssistant uses a directory, pegaGuiInstallerTemp, created in the directory from whichthe tool is run. If you leave the field blank, the Installation Assistant uses the user systemtemporary directory.

Important: The Assistant requires at least 3 GB of space during the installation process. Be surethere is enough disk space to allow the directory to grow to this size. The Assistant deletes alltemporary files at the end of the process.

Click Next to display the Rulebase Loading page.

106


6. Press START to begin loading the database with the rules.

Note: A typical installation can take 30 to 60 minutes depending on the speed of your system. Ifyou choose to pre-load the assembled rules cache, the process takes an additional 90 minutes.

When processing the larger files, the log can appear inactive for someminutes. Please allow theAssistant to finish.

The Assistant shows the progress through the stages of the installation:

107


Click Show Logs to see the log detail as the process is running.

108


Important:When the display shows that the rules have been loaded, perform aRUNSTATS on the database. This will significantly improve the performance of theremainder of the process.

The Assistant displays the following window when complete:

109


If the process does not complete:

Review information on the logs in the Output and Error tabs, and correct the problems.

Exit from the Assistant.

Clear the Process Commander database:

Using your database tools, run the drop SQL script in the schema\\util directory in the ProcessCommander software distribution, for example:

C:\PRPC_distribution\schema\\util\_drop_63.sql

Restart this Installation and Upgrade Assistant and complete the steps again as directed above.

5. When the process completes, the instructions for Step 10—Final Settings in PRPC opensin a browser window:

110


6. Click Exit in the Assistant and continue with the procedures in the next section Step 10—Final Settings in PRPC.

111


Step 10 - Final Settings in Process CommanderTo complete the installation, you login and configure settings in Process Commander.

Start and Login to Process CommanderAccess the Process Commander servlet, PRServlet, through a browser. Type in the URL for ProcessCommander application: http://<server>:<portnumber>/<context_root>/PRServlet. Forexample:

http://prpc-server:9080/prweb/PRServlet

The PegaRULES login screen (PRServlet) will be displayed:

Login to Process Commander:

– User Name: [email protected]– Password: install

The Process Commander Developer portal displays with a welcome message in the What’s Happeningsection of thepage:

112

Step 10 - Final Settings in Process Commander

Process Commander automatically launches a process to index the Process Commander rules in thesystem to support full-text search in the Developer environment. While this process is running, you maynotice some delay in the responsiveness of the Process Commander user interface. Depending on yoursystem, the indexing will complete in 10 to 15 minutes.

Note: This indexing process starts as soon as you start the Process Commander in the application server. Beforeyou login, you may notice this activity in your application server administrative console.

If you want to monitor the progress of the process, click here in the What’s Happening message.

Configure Process CommanderUse the Process Commander Landing pages, accessed from the Pega button, to configure your initialenvironment:

113


Enable Developer Help and the System Management ApplicationTo enable Help and the System Management Application, you must set the URLs that are used to accessthem.

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

2. Complete this page to specify the URLs to access the Help (prhelp.war) and SystemManagement (prsysmgmt.war) applications.

In the field Online Help URL, enter the URL for the prhelp.war file in the form:http://nodename:portnumber/prhelp.

Typically, you provide the name and port number of your Process Commander server, forexample, http://prpc_server:9080/prhelp

In the field for SMA URL, enter the URL for the System Management Application,prsysmgmt.war in the form http: //nodename:portnumber/prsysmgmt, for example,http://prpc_server:9080/prsysmgmt.

These applications are accessed from the Process Commander interface. Either applicationcan be deployed to a different application server than the core Process Commanderapplication.

Note: If you specify localhost as the server name, only users logged into the same server on whichthe applications are deployed are able to access the applications. Replace localhost with the actualserver name if you want to allow access to the applications from other Process Commander nodes.

3. In the field Public Link URL, you can also optionally provide a URL for your Process

114


Commander system to allow Directed Web Access, typically in the form:http://nodename:portnumber/PRServlet.

Directed Web Access (DWA) allows external users that do not have a ProcessCommander Operator ID to process an assignment in your application on a one-time basis.The URL you specify here is provided in an email to the external users to access ProcessCommander and may identify a proxy server. On the Pega Developer Network,(pdn.pega.com) see PRKB-24206: How to send an assignment by email to an external partyusing basic Directed Web Access.

4. Click Submit

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

Optionally Set Search Index Host Node SettingsSearch indexing supports the full-text search facility in Process Commander for rules, data instances,and work objects. By default, Search indexing is enabled and indexing starts automatically when youstart the application server after deploying Process Commander. Host Node Settings are set by defaultto your Process Commander node, and the Index directory is set to PegaRULESIndex in your ProcessCommander temporary directory.

You can change the default settings on the System – Settings landing page Search tab. From the Pegabutton, select System -> Settings -> Search.

115


For information about using this page, go to System category—Settings page in the Developer PortalOnline Help.

116


Create an Organization

1. From the Pega button, select the Org & Security > Organization Setup landing page:

2. In the Organization Name field, enter the name of your organization, leave the Actioncontrol set to Preview and click Run to review the objects and users that will be created.

Right-click in the window and select Print to print a record of this page.

Important: Be sure to preview and record the information on this page. The organization name youprovide will be used to create the initial users and access groups for your Process Commandersystem. You will need to know the user names to log on and begin using your Process Commanderinstallation.

3. Set the Action to Create and click Run to create the organizational structure.

4. Stop and restart the application server.

Change the password for [email protected]: To protect your system, be sure to change the password for the Operator [email protected]. The default password is widely published.

117


Install Solution FrameworksIf you are installing one of Pegasystems Solution Frameworks as part of your Process Commanderdevelopment environment, install the framework now. Follow the instructions in the Installation Guidefor the framework.

118


Process Commander Installation Guide - WebSphere 7 and DB2 · 2019-05-22 ·...

Documents

Transcript of Process Commander Installation Guide - WebSphere 7 and DB2 · 2019-05-22 ·...