PegaRULES Process Commander Release V6.1 SP2
Installing Process Commander Database: DB2 on z/OS Application Server: WebSphere
September 28, 2010
Copyright 2010 Pegasystems Inc., Cambridge, MA All rights reserved. This document and the software describe products and services of Pegasystems Inc. It may contain trade secrets and proprietary information. This information should not be disclosed to third parties unless otherwise provided for by a contract or business agreement with Pegasystems. This document and the software are protected by federal copyright law, international laws, and/or applicable treaties. This document is current as of the date of publication only. Changes in the document may be made from time to time at the discretion of Pegasystems. This document remains the property of Pegasystems and must be returned to it upon request. This document does not imply any commitment to offer or deliver the products or services provided. This document may include references to Pegasystems product features that have not been licensed by your company. If you have questions about whether a particular capability is included in your installation, please consult your Pegasystems service consultant. Other brand or product names are trademarks of their respective holders.
This document is the property of: Pegasystems Inc. 101 Main Street Cambridge, MA 02142-1590 Phone: (617) 374-9600 Fax: (617) 374-9620 www.pega.com PegaRULES Process Commander Document: Installation Guide Software Version: 6.1 SP2 Updated: September 28, 2010
Contents Introduction..................................................................................................................................... 1 Process Commander Deployment Architecture ................................................................... 1 Overview of the Installation Procedure ................................................................................. 3 Prerequisites ............................................................................................................................ 5 Important: Check the Pega Developer Network for the Latest Information ................ 5 Step 1: Environment Considerations........................................................................................... 7 Identify z/OS user IDs ...................................................................................................... 7 Configure your environment ........................................................................................... 8 Tailor the DDL to your environment ...................................................................................... 9 Step 2: Database Preparation ..................................................................................................... 13 Overview of the Process Commander Components .......................................................... 13 Creating the Database Step-by-step .................................................................................... 15 1. Allocate space to storage groups ........................................................................ 15 2. Create the z/OS libraries for Process Commander .............................................. 15 3. Prepare the Process Commander software distribution ..................................... 16 4. Move the library files from the distribution to the mainframe. ........................... 16 5. Set parameters in the PARMLIB library ................................................................ 18 6. Set Pega Properties ................................................................................................ 20 7. Verify the environment ........................................................................................... 22 8. Create the Database ............................................................................................... 22 Next Steps .............................................................................................................................. 24 Step 3: Preparing the Application Server .................................................................................. 25 Verify the Java Environment ................................................................................................ 25 Configure Support for the Process Commander Database ............................................... 26 Create a WebSphere Profile ................................................................................................. 27 Start and Configure the Server ............................................................................................ 28 Set JVM Requirements .................................................................................................. 29 Create URL Providers .................................................................................................... 34 Create JDBC Resources ................................................................................................ 38 Configure WebSphere WorkManager ........................................................................... 49 Other WebSphere Configuration................................................................................... 52 Deploy the PegaRULES core application ............................................................................ 57 Deploying prpc_j2ee14_ws.ear in WebSphere ............................................................ 58
iv
Pegarules Process Commander Installation Guide V6.1 SP2
Installing the System Management and Online Help Applications ................................... 65 Assigning the PegaDiagnosticUser Role to your System Management Application Users ................................................................................................................................................ 70 Deploying a Multi-Servant System (Optional) ..................................................................... 73 Next Steps ....................................................................................................................... 76 Steps 4 - 9: Rulebase Setup........................................................................................................ 77 Load Process Commander Rules in the Database ............................................................. 77 Step 10: Final Settings in Process Commander ....................................................................... 89 Configure your environment ................................................................................................ 90 Enable Developer Help and the System Management Application ............................ 91 Create an Organization .................................................................................................. 92 Install Solution Frameworks................................................................................................. 93 Appendix A: Pega Library Members .......................................................................................... 95 Pega Parameter Library (PEGA.DB2.PARMLIB) Members ......................................... 95 Pega Control Library (PEGA.DB2.CNTL) JCL Members ............................................. 97 Appendix B: Pega Database Tables, Views, Triggers and Stored Procedures .....................102
Introduction This document describes how to install a new instance of PegaRULES Process Commander 6.1 SP2 using DB2 on z/OS as the database and WebSphere as the application. These documents and any updates to existing Process Commander documentation are available on the Pega Developer Network (pdn.pega.com). Please check this site for the latest installation and configuration information.
Process Commander Deployment Architecture Process Commander is a Java EE enterprise application. As shown in the diagram below, it runs on top of two main platform sub-systems: 1. A database system to store the rules and work objects used and generated by Process Commander. 2. An application server that supports the Java EE specification, in this case IBM’s WebSphere application server. The application server provides a run-time environment and other services, such as database connections, Java Messaging Services (JMS) support, and connector and services interfaces to other external systems.
2
PegaRULES Process Commander Installation Guide v6.1 SP2
Both developers working on Process Commander applications and users working with those applications access Process Commander through Web browser interfaces.
3
Overview of the Installation Procedure The following outline details the steps in the 6.1 SP2 installation process: Preparation Phase
Step 1 – Environment Considerations Step 2 – Database Preparation Step 3 – Application Server Preparation
Rulebase Setup Phase
Step 4 - License Agreement Step 5 - Type of Setup Step 6 - Database Configuration Step 7 - Database Connection Step 8 - Temporary Directory Step 9 - Rulebase Loading
Process Commander Configuration Phase
Step 10 – Final Settings in PRPC
Installing Process Commander includes 10 steps organized into three phases:
1. Preparation Phase You complete the Preparation Phase following the procedures in this guide. ■
Step 1: Environment Considerations, page 7 .
Make sure that your environment meets the requirements for Process Commander 6.1 SP2 for hardware, operating system, JVM, JDBC Driver, application server, and database server. 1. Review the current Platform Support Guide, which is available on the Pega Developer Network (PDN) or from your Pega account executive. This document lists the recommended software components needed to support Process Commander, and any special requirements or known issues with particular vendors or versions. 2. Review your site’s deployment requirements with your IT or System Administration representatives. 3. Consult with your Pegasystems representative about your installation plans. Pegasystems’ prior experience with various platforms and deployment architectures can help your installation go smoothly.
4
PegaRULES Process Commander Installation Guide v6.1 SP2
■
Step 2: Database Preparation, page 7.
Create and configure a empty database for Process Commander to use. You can use SQL scripts provided by Pegasystems to create the schema required by Process Commander in the database, or you can 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 in the Rulebase Setup Phase and you specify the datasource in your application server. The connection information you will need includes the location of the JDBC driver file, the driver class name, the database 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 in the Rulebase Setup Phase can be performed in either order or simultaneously. You can, for example, launch the Rulebase Setup process in Step 9 of the Assistant and then configure your application server while the Rulebase load process is running. However, you must configure the application server and deploy the Process Commander applications before you can complete Step 10, PRPC Final Settings.
Important: You must be careful not to start the deployed Process Commander applications while the Rulebase loading process is still running on the database. Note that your application server may start the application automatically when it is deployed. If the Process Commander application attempts to connect to the database while the Rulebase is loading, the database loading will not complete correctly. ■
Step 3: Application Server Preparation, page 25.
Configure your application server to support the Process Commander application, including: 1. Configure the right Database Driver for your Database 2. Configure the Process Commander Data Source 3. Configure other 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 Phase You 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 on page 77 .
5
The Installation Assistant optionally creates the Process Commander schema in the database instance you provide, and installs the initial set of rules and classes Process Commander needs to run into the database.
3. Process Commander Configuration Phase You complete the Process Commander Configuration Phase after finishing the Installation by logging into Process Commander. The setup steps you should complete in Process Commander are described in section Step 10: Final PRPC Configuration Steps, page 90.
Prerequisites The prerequisites for installing Process Commander are: ■
An application server host computer with adequate memory and disk space for the installation.
Process Commander requires a minimum of one GB of free memory. This is in addition to any memory allocated for the operating system or other applications on the server. The memory required for your system may need to be higher, depending on the number of users and your specific configuration. ■
A working installation of a Java EE compliant application server, in this case WebSphere.
Process Commander Installation Guides for each supported application server are available with your Pegasystems software distribution and on the Deployment page of the Pega Developer Network (http://pdn.pega.com). ■
A configured relational database available for Process Commander use, and support in your organization for the installation and configuration of relational databases.
The database and application server platforms may be z/OS, UNIX or Windows systems. However, a Windows system is required for the Pegasystems developer and end-user clients and for some of the Pegasystems monitoring tools, specifically, PegaRULES® Process Analyzer™, Process Simulator™. The environment for your initial Process Commander system should include at least one Windows platform.
Note: If you have difficulty installing any of the third-party software required by Process Commander, contact the other software vendor to resolve the issues before installing Process Commander.
Important: Check the Pega Developer Network for the Latest Information Before beginning your installation procedure, check the Pega Developer Network (PDN), located at http://pdn.pega.com, for the latest information. The installation
6
PegaRULES Process Commander Installation Guide v6.1 SP2
guides are updated whenever new information becomes available. Be sure to check for the latest version.
Pegasystems Documentation The latest Process Commander documentation, including Installation, Upgrade, and Platform Support guides 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 updates Check the Deployment page on the Pega Developer Network for information, updates, and platform bulletins 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 Training A range of Pegasystems course offerings are available to increase the effectiveness of your deployment and development team members. For more information, visit http://www.pega.com/Services/EducationalServices
7
Step 1: Environment Considerations — Before You Begin Identify z/OS user IDs Process Commander requires z/OS log-on credentials to create the DB2 database and to access it once created. You provide this username and password in the DBPROPS member of PARMLIB library, as described below, and when you configure data access for Process Commander in your application server. 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 MVS 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 all objects within a database
■
DB2 database INSERT, UPDATE and DELETE authority.
■
DB2 database grant access to execute stored procedures.
Best Practices: You can create two users with whose only difference would be the database
8
PegaRULES Process Commander Installation Guide v6.1 SP2
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 SQL INSERT, DELETE, UPDATE, and SELECT statements.
Supply
Configure your environment 1. Obtain the following from your DB2 System Programmer or DB2 DBA: –
A ‘batch SPUFI’ catalogued procedure. Obtain a copy of a working example. This install cannot proceed without either DSNTEP2 or DSNTEP4 (both IBM supplied programs) functioning properly. See DSNTEJ1l or DSNTEJ1P of DSN810.NEW.SDSNSAMP. In the CNTL distribution library we provide PEGAINST as an example.
–
A working example of a DSNHSQL procedure. This is required to create the stored procedures. In CNTL we provide PEGHSQL as an example.
–
The location name and port number of the DB2 subsystem you wish to access. Every time the DDF address space starts, it reports this value on the system console.
–
A copy of a working TSO logon proc. This may be needed to run the REXX tailoring scripts in batch. We provide BTCHISPF as an example. All this JCL needs are sufficient library allocations to be able to run the ISPF editor in batch and find our provided REXX execs. You need this TSO procedure if you decide to use the Pegasystems provided tailoring scheme.
2. Locate the CDROM containing PRPC software. 3. If you use external stored procedures for the Process Commander system, work with your DB2 DBA to select a Work Load Manager (WLM) Application Environment Name for this database. After tailoring the JCL, ensure that the WLM proc is correctly installed in a system Procedure library. PRPC will not start if the PRPC stored procedures will not run. 4. Determine whether your site currently supports SQL-based stored procedures. If you use external stored procedures, this support requires, for installation purposes only, that a C compiler is available on z/OS. Further it requires that you have tailored and executed sample jobs DSNTEJ63, DSNTEJ64, DSNTEJ65 from DSN810 or DSN910 “.NEW.SDSNSAMP”.
9
See sample job DSNTIJMV in the same library for the details of the DSNHSQL proc discussed above. It is sufficient if you can confirm that these jobs have been successfully completed. 5. Ensure that you have enabled New Function Mode on your DB2 for z/OS Version 8 or Version 9 subsystem. 6. This version of PRPC has been tested with DB2 for z/OS Version 8 and Version 9. 7. Pegasystems recommends the following ZPARM settings for any DB2 subsystem supporting our products. Some of these parameters apply only to Version 9. Contact your DB2 for z/OS system programmer and ensure that the following ZPARM values have been evaluated. A: CACHEDYN=YES B: CMTSTAT MAY BE INACTIVE OR ACTIVE. C: DESCSTAT=YES. (Mandatory). D: IDBACK=200 (Minimum). E: IDFORE=200 (Minimum) F: IDTHION=300 (Minimum if CMTSTAT=INACTIVE) G: LOBVALA=10240 (minimum) H: LOBVALS=2048 (minimum) I: NUMLKTS=5000 (Minimum) J: NUMLKUS=30000 (Minimum) K: OPTIOWGT=ENABLE L: OPTIXOPREF=OFF M: OPTXQB=OFF (TEMPORARY A/O 5/09 DUE TO IBM APARS). N: STATCLUS=ENHANCED. O: SKIPUNCI=YES (V9 Only).
Tailor the DDL to your environment Working with your DBA and Data security team, identify your selections for each of the following variables. Enter your updates in the middle column as documentation for your installation. Later in the Installation procedure, you enter these values in the PEGPROPS member of the PARMLIB library.
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 PRPC system. As your unique requirements, and use case, evolve, some of these values may change.
Variable with Default LOB Parameters
Your Choice
Description
10
PegaRULES Process Commander Installation Guide v6.1 SP2
Variable with Default
Your Choice
Description
#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
#DBUSER=PEGDB
PRPC Database user
11
Variable with Default
Your Choice
#SYSADM=SYSADM
Description 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
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 shop standards. The value you select here will be substituted everywhere in the target libraries that DB2 expects a valid database name. PRPC has no special requirements for this name other than that it be acceptable to DB2. This installation procedure assumes that the entire database can be dropped and recreated. Carefully consider placing any nonPEGASYSTEMS related database objects in this schema.
■
#DBOWNR will be the database owner for the libraries copy of the PRPC database. This install procedure assumes that #DBOWNR has DBADM on #DBNAME either directly via grant or indirectly via Secondary Authorization ID processing. The PRPC application servers can logon to this database using #DBOWNR. Note that this installation procedure will create a PLAN_TABLE owned by #DBOWNR.
■
#DBUSER will be the PRPC database accessor id. For many shops that strictly enforce segregation of duties, 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.
■
#SYSADM is a user id that has create database with grant privileges on the target subsystem represented by #SSID and #Location. #SYSADM is assumed to have both the create database and grant privilege.
12
PegaRULES Process Commander Installation Guide v6.1 SP2
■
#SSID is the unique system identifier that allows allied address spaces to connect to a specific DB2 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/OS manuals for details on setting this value.
■
Assign separate storage groups for table spaces, index spaces, and LOB table spaces. Should you 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 we recommend setting the Deferred Write Threshold “DWQT” to zero. By default, this installation procedure defines all LOB table spaces as LOG YES. Pegasystems recommends segregating LOB 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 #DBOWNR userid. If you wish to use #DBUSER see chapter 4 for the details on the changes necessary.
13
Step 2: Database Preparation To prepare your database server to use with Process Commander, you must complete the following tasks: 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. Set Pega Properties 7. Verify the environment 8. Create the Database
Overview of the Process Commander Components To prepare the Process Commander database on z/OS you allocate and load the following libraries from the Process Commander software distribution to you z/OS environment. ■
Four Pega base libraries that you will use to create the database: –
PEGA.DB2.PARMLIB The Pega Parameter library contains members, (DBPROPS, PEGPROPS, USERENV, and UPGFILES) which provide a single point to enter site specific information needed to create a DB2 database for a Process Commander installation.
For a full inventory of the members of these libraries see “Pega Parameter Library (PEGA.DB2.PARMLIB) Members” on page 95.
14
PegaRULES Process Commander Installation Guide v6.1 SP2
–
PEGA.DB2.CNTL The Pega Control library that contains the JCL that is used for creating a DB2 database for Pega installation. For a full inventory of the members of these libraries see “Pega Control Library (PEGA.DB2.CNTL) JCL Members” on page 97.
–
PEGA.DB2.DDL The Pega Database Definition Library that contains members that control the execution of DB2 utilities for creating a DB2 database for Pega installation.
–
PEGA.DB2.PROCLIB The Pega Procedure library that contains the procedures executed by the JCL in the Pega Control library to create a DB2 database for installing Pega Rules.
■
Two product libraries that contain the media required to define the database components necessary to install and run Process Commander. –
PEGA.PEG61SP2.DDL This library contains the product’s DDL (Database Definition Language) members that are the SQL definitions needed to create all the product’s database components except the stored procedures.
–
PEGA.PEG61SP2.SOURCE This library’s members contain the source necessary to create all the product’s database stored procedures.
Similar libraries will be distributed to prepare the database for the Process Commander Frameworks Solutions. Before running the JCL jobs that build the Process Commander database definition, you provide information about your environment in two properties members in PEGA.DB2.PARMLIB: ■
You use the PEGPROPS properties member to specify database parameters used by the Process 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
15
You specify the name for this member in the environment member, USERENV, in the PROPNAME variable. It is recommended that you name this member the same name as your database name. ■
You use the user environment member, USERENV, to specify parameters that identify your environment to the Pega JCL used to create and update Pega DB2 database instance. Copy this member to a member name that matches the database owner’s id. The database owner’s id is the TSO/Batch user id name that the database is going to be created under. This member identifies the following general Process Commander resources in your environment: –
The Pega Base Create and Maintenance libraries.
–
The Pega Product libraries that contain the statements to define or upgrade the Pega database instance for the appropriate Pega product.
–
Points to the database properties file used to create or update a particular Pega database instance.
–
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.
Creating the Database Step-by-step 1. Allocate space to storage groups Identify the database space requirements for an initial install. Ensure that the Storage Groups and Buffer pools selected for use by Process Commander are created, and permission is granted to the #DBOWNR userid to use them. Allocate at least 4GB to the database to load the initial Process Commander RuleBase and do simple development. For production, you may need up to 50 to 100 GB.
2. Create the z/OS libraries for Process Commander Pre-allocate the following sequential datasets to simplify the process of moving the Process Commander libraries to z/OS. The DCB information must be as given below: ■
PEGA.DB2.CNTL –
DCB=(DSORG=PO, LRECL=80,BLKSIZE=6400)
–
DSNTYPE=LIBRARY,SPACE=(CYL,(1,1))
16
PegaRULES Process Commander Installation Guide v6.1 SP2
■
■
■
■
■
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.PEG61SP2.DDL –
DCB=(DSORG=PO, LRECL=80,BLKSIZE=6400)
–
DSNTYPE=LIBRARY,SPACE=(CYL,(1,1))
PEGA.PEG61SP2.SOURCE –
DCB=(DSORG=PO, LRECL=80,BLKSIZE=6400)
–
DSNTYPE=LIBRARY,SPACE=(CYL,(1,1))
3. Prepare the Process Commander software distribution 1. Determine a location that has FTP access to your MVS on a Windows desktop, a Linux for System Z desktop, or z/OS USS. 2. Download the Process Commander image, PRPC_DistributionImage.zip, or copy it from your Pegasystems software CD, to that location. 3. Expand PRPC_DistributionImage.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 PRPC_DistributionImage.zip
This command expands the archive in the current working directory.
4. Move the library files from the distribution to the mainframe. If you uncompress the PRPC_DistributionImage.zip on a Windows machine you must still transfer the following files to 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
–
schema\db2zos\libraries\ PEGA.DB2UPG.STDPARM
17
In addition, you must transfer the following directories and their contents: –
schema\db2zos\ EBCDIC\install or schema\db2zos\ UNICODE\install
–
schema\db2zos\ EBCDIC\install\source or schema\db2zos\ UNICODE\install\source
–
schema\db2zos\upgrade
Important: If you expand the PRPC distribution on a Windows system, you must convert the files from the Unix End Of Line (EOL) character, LF, to the Windows format, CR/LF, before you can FTP them to your z/OS system. There are many free tools available to do Unix2Dos conversion if your shop does not already have such a utility. If necessary, you can contact Pegasystems Global Customer Support for assistance.
Example FTP Session The following is a example of an FTP session in a Windows command prompt window that moves the files correctly to a mainframe. In the example, information you enter is highlighted in yellow. Modify the entries as needed for your environment. Microsoft Windows XP [Version 5.1.2600] (C) Copyright 1985-2001 Microsoft Corp. C:\Documents and Settings\pegauser>d: D:\>cd \zSeries\coreDistributionImage D:\zSeries\coreDistributionImage>ftp ftp> open zos Connected 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)): pegauser 331 Send password please. Password: 230 PEGAUSER is logged on. Working directory is "PEGAUSER.". ftp> ascii 200 Representation type is Ascii NonPrint ftp> cd "'PEGA.DB2.CNTL'" 250 The working directory "PEGA.DB2.CNTL" is a partitioned data set ftp> lcd .\schema\db2zos\libraries\PEGA.DB2.CNTL Local directory now D:\zSeries\coreDistributionImage\schema\db2zos\libraries\PEGA.DB2.CNTL. ftp> prompt Interactive mode Off . ftp> mput * 200 Port request OK. 125 Storing data set PEGA.DB2.CNTL(PC00REN) 250 Transfer completed successfully.
18
PegaRULES Process Commander Installation Guide v6.1 SP2
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> bye 221 Quit command received. Goodbye. D:\zSeries\coreDistributionImage>
To install a Process Commander database, FTP the files from the following directories to the allocated libraries: Directory From
Library TO
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 or
PEGA.PEG61SP2.DDL
mput PEG*
PEGA.PEG61SP2.SOURCE
mput *
schema\db2zos\UNICODE\install schema\db2zos\EBCDIC\install\source or schema\db2zos\UNICODE\install\source
5. Set parameters in the PARMLIB library 1. Open the Pega PARMLIB library (PEGA.DB2.PARMLIB or your equivalent dataset name) for editing. 2. Copy the USERENV member to the name of the TSO/Database Owner userid that is going to be used to create the database by running the Create JCL jobs.
19
3. Edit your copy of USERENV and review each line in this renamed member making the appropriate environmental changes to the values to reflect your environment. For example: //*-------------------------------------------------------------* //* //* Pega JCL environment install settings //* //*-------------------------------------------------------------* //*-------------------------------------------------------------* //* //* Properties that identify the Pega Base Install Libraries //* //*-------------------------------------------------------------* //* //SETJCL
SET PEGAJCL=PEGA.DB2.CNTL
//SETPROC
SET PEGAPRC=PEGA.DB2.PROCLIB
//SETDDL
SET PEGADDL=PEGA.DB2.DDL
//SETPARM
SET PEGAPRM=PEGA.DB2.PARMLIB
//* //*-------------------------------------------------------------* //* //* Properties that identify the Pega Product Install Libraries //* //*
Values shown are for the Pega Rules Process Commmander
//* //*-------------------------------------------------------------* //* //SETTYPE
SET PEGPFX=PEG
//SETPDDL
SET PRDDDL=PEGA.product.DDL
//SETPSRC
SET PRDSRC=PEGA.product.SOURCE
//* //*-------------------------------------------------------------* //* //* Properties that identify the Pega Product Upgrade Libraries //* //*
Values shown are for the Pega Rules Process Commmander
//* //*-------------------------------------------------------------* //* //SETUDDL
SET UPGDDL=PEGA.product.DDL
//SETUSRC
SET UPGSRC=PEGA.product.SOURCE
//* //*-------------------------------------------------------------* //* //* The following properties are used to identify the DB2
20
PegaRULES Process Commander Installation Guide v6.1 SP2
//*
required libraries for install
//* //*-------------------------------------------------------------* //* //SETPROPS SET PROPNAME=property-name //SETDSYS
SET DB2SSID=DB9G
//SETDVER
SET DB2VER=910
//SETDBLQ
SET DB2HLQ=DSN910
//SETDEXIT SET SDSNEXIT=SDSNEXIT //SETDLOAD SET SDSNLOAD=SDSNLOAD //SETDSAMP SET SDSNSAMP=SDSNSAMP //SETDPROC SET SDSNPROC=PROCLIB //SETDRLIB SET SDSNRLIB=RUNLIB.LOAD //SETDCHDR SET SDSNCHDR=SDSNC.H //* //*-------------------------------------------------------------* //* //* The following properties are to identify the libraries to //*
be used to install and then run Pega DB2 Stored Procedures
//* //* Replace hlq with your High-Level-Qualifier //*
and mlq with your Middle-Level-Qualifier
//* //*-------------------------------------------------------------* //* //SETCSRC
SET DB2CSRC=hlq.mlq.CSRC
//SETDBRM
SET DB2DBRM=hlq.mlq.DBRM
//SETLOAD
SET DB2LOAD=hlq.mlq.LOAD
//SETPNAM
SET PROCNM=wlm-proc-name
//SETUPRC
SET YOURPROC=customers-user-proclib
6. Set Pega Properties 1. Open the Pega PROCLIB library (PEGA.DB2.PROCLIB or your equivalent dataset name) for editing. 2. Copy the PEGPROPS member to the 8 character database name that is going to be used for Pega. 3. Review each line in this renamed property member making the appropriate changes to the values to reflect your environment. These properties correspond to the values you collected above in “Tailor the DDL to your environment” on page 9. For example: ##
21
## LOB Parameters ## #BLBBFP
= BP4
#BLBBP16
= BP16K0
#BLBLCK
= LOB
#BLBLCM
= 0
#BLBLOG
= YES
#BLBPRI
= 720
#BLBSEC
= 7200
#BLBSTG
= PEGBLBS9
(Blob.Storage.Group.Name)
## ## Index Parameters ## #IDXBP
= BP2
#IDXPRI
= 720
#IDXSEC
= 7200
#IDXSTG
= PEGIDXS9
(Index.Storage.Group.Name)
## ## Table Space Parameters ## #TSPLCK
= PAGE
#TSPLCM
= 0
#TSPPRI
= 720
#TSPSEC
= 7200
#TSPSTG
= PEGTSPS9
#TSP4BP
= BP5
#TSP8BP
= BP8K0
#TS16BP
= BP16K0
#TS32BP
= BP32K
(Table.Storage.Group.Name)
## ## Database Access Parameters ## #CCSID
= EBCDIC
#DBNAME
= PEGDB
#DBOWNR
= PEGDBDBO
#DBUSER
= PEGDB
#SYSADM
= SYSADM
## ## Package Collection for Stored Procedures ## #COLLECTION = PEGDBCOL
(collection.name)
## ## Work Load Manager Parameters ## #SPLOAD
= the.same.as.the.USERENV.DB2LOAD.property
#WLMAPPENV
= PEGDBWLM
(wlm.application.environment.name)
22
PegaRULES Process Commander Installation Guide v6.1 SP2
#SSID
= DB9G
#DB2HLQ
= DSN9108. Verify the environment
7. Verify the environment In the PEGA.DB2.CNTL library, run the following verify jobs to confirm that the environment values 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 which executes the Pega data parser and the IBM DB2 module SPUFI (SQL Processing Using File Input) to process the parser data runs without a problem. 2. PV02UTIL Runs the DB2 utility function. It verifies that the IBM DB2 utilities module runs without a problem. 3. PV03SPUF Runs your computer’s DB2 SPUFI in batch. It verifies that the IBM DB2 module SPUFI (SQL Processing Using File Input) runs without a problem.
8. Create the Database To create the schema, tables, stored procedures and trigger, you run the a sequence of jobs in the PEGA.DB2.CNTL library. You can create the database with native stored procedures, located in the database, or external stored procedures, located outside the database. Both procedures are outlined below.
To create the database to use native stored procedures Run the following jobs in sequence. 1. PC00REN (Run only if you change the dataset names from Pega.DB2.*). Dynamically renames the z/OS datasets PEGA.DB2.PROCLIB and PEGA.DB2.PARMLIB in all members of the Pega JCL library PEGA.DB2.CNTL. Use this member to set the dataset names to match your site’s standards. You specify the names to use by editing parameter cards in the member to the names that were allocated for the Pega libraries. 2. PC01CDB Create the database Creates the DB2 database definition that will be used for the Process Commander system. 3. PC02NDB Builds all the Pega database structures in DB2 for a database that uses native stored procedures, including:
23
–
table spaces
–
tables
–
LOB table spaces
–
LOBs, indexes
–
views
–
triggers
–
native stored procedures.
To create database to use external stored procedures 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 all members of the Pega JCL library PEGA.DB2.CNTL. Use this member to set the dataset names to match your site’s standards. You specify the names to use by editing parameter cards in the member to the names that were allocated for the Pega libraries.PC01CDB Create the database 2. PC02BDB Build 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 stored procedures used by the Process Commander system: CSRC, DBRM, and LOAD. You specify the libraries dataset names in the USERENV member of the Process Commander system PARMLIB library, by default PEGA.DB2.PARMLIB. 4. PC06GSP Generate Stored Procedures auto submits PC06CSP Create Stored Procedures. Generates the JCL to compile, link and create external stored procedures used by the Process Commander system, and submits the JCL to build the stored procedures on behalf of the user as job PC06SP from PROCLIB. 5. PC07BPT Build Plan Table for Stored Procedures Creates the bind plan tables for the external stored procedures that are used by the Process Commander Rules system. 6. PC08RNS Run Stats Runs the DB2 utility, RUNSTATS, to update the database statistics used for
24
PegaRULES Process Commander Installation Guide v6.1 SP2
determining access paths to the database. 7. PC09BND Bind Stored Procedure to Plan Tables Binds all Process Commander external stored procedures to the plan tables that were defined in job PC07BPT. 8. PC10TRG Create database triggers Defines all triggers used by the Process Commander system to the DB2 database definition. 9. PC11GRT Issue grants for tables, stored procedures and database. Grants permissions for the Process Commander tables, stored procedures and the stored procedure collection package to the user ids created to access the DB2 database. You specify these user ids in the DBPROPS member of the Pega system PARMLIB library, by default PEGA.DB2.PARMLIB. 10. PC12CPY Copy Work Load Manager procedure to customer’s user system PROCLIB. Copies the work load manager (WLM) procedure that defines the WLM application used to run and control the Pega external stored procedures from the Pega PROCLIB library to the user’s system PROCLIB.
Start Work Load Manager Define and start WLM (work Load Manager) application that uses the WLM procedure copied in PC12CPY, You may need to consult your System Programmer about this step. You may now move on to loading your rules, please consult the appropriate section of the installation manual.
Next Steps You can continue either with Step3, Application Server Configuration, or Steps 49, Rulebase Setup. These two procedures are independent and can be completed in either order or simultaneously. Note, however, that you cannot run Process Commander successfully until the database setup is complete. If you deploy and start the Process Commander application before the database is complete, the application generates errors.
25
Step 3: Preparing the Application Server This chapter describes the tasks you must complete on your application server before beginning to deploy the Process Commander application: ■
Verify the Java Environment
■
Configure Support for the Process Commander Database
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 Environment Confirm that the Java JDK environment used by your application server is Java JDK 1.5.0_07 or higher. Refer to the Platform Support Guide, available as a PDF file on the Pega Developer Network (PDN) located at http://pdn.pega.com, for specific recommendations for your platform.
Important: During installation, Process Commander requires access to the directory specified by the java.io.tmpdir setting in the JVM. Confirm that there is write access to this directory before installing Process Commander.
26
PegaRULES Process Commander Installation Guide v6.1 SP2
Be sure your application server is configured to use an appropriate JDK. The default Java environment for your application server may not be one of the recommended JDKs for Process Commander.
Configure Support for the Process Commander Database In order to support JDBC connections between your application server and the Process Commander, you must install the appropriate database client software and JDBC drivers on your application server as recommended by your database vendor. Follow the IBM instructions for installing the client software and the JDBC drivers to make the db2jcc.jar available. This JDBC driver is the Type 4 universal driver. Configure the application server so that this driver is loaded in the classpath.
27
Deploying Process Commander in WebSphere 7.0 This section describes a sample deployment procedure for Process Commander 6.1 SP2 on WebSphere 7.0. If you are installing 6.1 SP2 on an earlier WebSphere release, the Administration Console screens and fields will vary from those described below, and you may need to make some modifications to the configuration settings specified. Be sure to contact Pegasystems Customer Support before installing Process Commander on a hardware and software platform that does not conform to one of the supported platforms for this release.
Create a WebSphere Profile Run the WebSphere Profile Management Tool to create a WebSphere profile in which to run the Process Commander application. You must create a new profile dedicated to Process Commander, so that Process Commander can run in its own JVM environment. You may use either the Typical profile creation or the Advanced profile creation option. The Typical profile assigns default values for such things as the Profile name, Node name, Host name, and access ports. Advanced Profile creation lets you change the defaults. Both methods allow you to choose whether to apply Administrative Security requiring a login with user name and password when starting the 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 by default. This means that you must manage the profile as a Windows service, for example when starting and stopping the server. If you do not want to run the application as a Windows service, choose the Advanced profile creation option and, on the Windows Service Definition page, do not check Run the application server process as a Windows Service. Make sure you record the following information about the profile you create:
28
PegaRULES Process Commander Installation Guide v6.1 SP2
■
Profile name
■
User name and password for the Administrative Console (if you choose to apply Administrative Security.)
■
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 Administrative console secure port, the HTTPS transport port, and the SOAP connector port. If you are unsure about these requirements, check with your application server administrator For information on WebSphere Profiles, go to the WebSphere online documentation at http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jspl, and search for “Creating and deleting profiles.”
Start and Configure the Server 1. 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 Administrative Console from the Start menu, for example, in a default installation: –
To start the server, click Start > All Programs > IBM WebSphere > Application Server v7.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 will need to login using the user name and password you specified at that time. When the Administrative Console is launched, it displays the Welcome screen for WebSphere’s Integrated Solution Console:
29
2. Click the link WebSphere Application Server to display the Welcome page for the application server:
Set JVM Requirements Setting Memory Parameters Set these memory parameters as described below: ■
Initial Heap Size: 768
■
Maximum Heap Size: 1024
If your application server is using the Sun JVM, add the PermSize and MaxPermSize settings as well: ■
PermSize: 64MB
■
MaxPermSize: 256MB
1. In the Administrative window, on the left side of the screen, click Servers > Server Types > Websphere application servers.
30
PegaRULES Process Commander Installation Guide v6.1 SP2
2. Find the name of the server on which Process Commander will run, and click that server name. (In the example above, the server is server1.) The Configuration tab for that server appears.
31
3. In the Server Infrastructure section, click Java and Process Management > Process Definition. (You may need to scroll down in the window to see the Server Infrastructure section.) This displays the Configuration tab for command-line settings:
4. In the Additional Properties section, click Java Virtual Machine. This displays the Configuration tab for the Java Virtual Machine.
32
PegaRULES Process Commander Installation Guide v6.1 SP2
5. On this window set: –
Initial Heap Size of at least 768
–
Maximum Heap Size of at least 1024
Note: These values are initial minimum estimates for typical development systems. They may need to 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. Setting the Initial and Maximum heap sizes to the same value helps to avoid the performance costs of heap contraction and expansion. All of the memory is allocated at startup. However, if you set an initial heap size lower than the maximum, you may find that the heap does not grow to the maximum size. Consult with your System Administrator to tune these settings to the best values for your environment.
33
6. If your WebSphere instance is using the Sun JVM, in the Generic JVM Arguments field also set a PermSize of 64MB and a MaxPermSize of 256MB by entering: -XX:PermSize=64m -XX:MaxPermSize=256m
Separate the JVM Arguments with a space between each. Do not use commas. 7. Click Apply to apply these settings. A message appears at the top of the screen explaining that the changes were made.
8. Click Save within the message to save these changes to the master configuration. You are returned to the Process Definition page.
Enabling AWT to support Process Commander Graphs--UNIX Only If you are deploying Process Commander on any of the UNIX platforms (Solaris, AIX, HPUX, Suse or RedHat Linux,) complete the following steps: 9. Still on the Application Servers > server1 > Process Definition page, under Additional Properties, select Java Virtual Machine to return to the Configuration page. 10. In the Generic JVM Arguments field, enter the following system property JVM argument:: -Djava.awt.headless=true
For example,
Note: Separate this argument from any others in the field with a comma. 11. Click Apply. 12. In the Messages section at the top of the page, click Save.
34
PegaRULES Process Commander Installation Guide v6.1 SP2
This setting enables the server to render graphics that are required to produce the Process Commander graphical reports.
Create URL Providers Follow the procedure below to set the required URL Pega reference and an explicit Temporary directory for Process Commander. The temporary directory is used by Process Commander to store static data. It is important that the directory be properly specified and accessible to the Process Commander user. In WebSphere you specify this directory as a JNDI reference to a URL object. 1. In the WebSphere Administration console select Resources > URL > URL Providers in the left frame.
2. Set the Scope level appropriate to your deployment, and click on the Default URL Provider link. In the following example, the scope is set to the server level.
35
3. Under the Additional Properties section, click on the URLs link to display the URLs listing page:
4. Click New to display the Configuration page:
36
PegaRULES Process Commander Installation Guide v6.1 SP2
5. Define a URL for the NULL file that Process Commander can use to discard erroneous error messages 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:///null for Windows or file:///dev/null for UNIX/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.
37
8. Complete this form to create a URL specification for a temporary directory that Process Commander 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 temporary directory. Enter the path using forward slashes for both Windows and UNIX platforms. For example, on Windows the value might be: file:///D:/Temp/PegaTempDir.
Important: The directory names you enter here are case sensitive. Be sure to enter the names of the directories exactly as they have been created on your system.
Notes: If the directory you specify does not exist, Process Commander will attempt to allocate it. It is 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 is accessible under your security policy. In a clustered deployment, each Process Commander instance must have its own temporary directory. You cannot share a temporary directory with more than one Process Commander instance.
38
PegaRULES Process Commander Installation Guide v6.1 SP2
9. Click OK and then Save in the confirmation message.
Create JDBC Resources Create a JDBC provider 1. In the Administrative console, click Resources > JDBC > JDBC Providers to display the JDBC Providers page:
2. In the Scopes dropdown, choose the scope level appropriate to your deployment, and click New to display the JDBC provider wizard:
39
3. Complete the fields in Step 1 as follows: –
In the Database type dropdown, select: DB2.
–
In the Provider type dropdown, choose DB2 Universal JDBC Driver Provider.
–
In the Implementation type dropdown, select Connection pool data source.
–
In the Name and Description fields, accept the defaults.
Click Next to display Step 2:
40
PegaRULES Process Commander Installation Guide v6.1 SP2
In the Directory location field, confirm the entry, if one is displayed, or enter the path to the driver class files listed in the Class path field, db2jcc.jar, db2jcc_javax.jar, and db2jcc_license_cisuz.jar. 4. Click Next to display Step 3.
5. Confirm that the settings are correct, and click Finish.
41
You are returned to the JDBC Providers page.
6. Click Save in the confirmation message.
Create Data Source 7. Still on the JDBC providers page, click on the name of the provider you just created to display the General Properties page.
42
PegaRULES Process Commander Installation Guide v6.1 SP2
8. Under the Additional Properties heading, click Data Sources.
9. Click New to display the data source wizard:
43
10. Define the data source name and JNDI name as described below. –
In the Data Source name field, enter PegaRULES
–
In the JNDI name field, enter jdbc/PegaRULES.
–
Click Next to display Step 2:
11. Supply information about your Process Commander database. If you are unsure about the information to supply for your database server, consult with your site DBA. Click Next.to display Step 3:
44
PegaRULES Process Commander Installation Guide v6.1 SP2
12. Click Next on Step 3 to display the Summary page. (You will supply DB credentials in a later step):
13. On the Summary page, confirm that the settings are correct and click Finish.
45
You are returned to the JDBC Providers page.
14. Click Save in the confirmation message. 15. Still on the Data Sources page, click the PegaRULES link in the Name column to open the Configuration page for this data source. Then, under Additional Properties, click on the Custom Properties link to display the Custom Properties page:
16. Click New to define the additional properties for your database connection. here.
46
PegaRULES Process Commander Installation Guide v6.1 SP2
To create each new property, click New on the Custom Properties form. After creating each property, click OK to save the property, and New again to create the next property. Be sure to set the Type field appropriately for the Value of the connection property. Process Commander requires the following properties for DB2: –
Name: currentSchema
Value:
Note: Be sure to enter the schema name in all capital letters. –
Name: currentFunctionPath
Value: SYSIBM, SYSFUN,
Note: SYSIBM and SYSFUN are system schemas provided by DB2. They are required because Process Commander 6.1 SP2 makes use of some functions made available in these schemas. –
Name: fullyMaterializeLobData
Value: true
–
Name: fullyMaterializeInputStreams
–
Name: progressiveStreaming
–
Name: progressiveLocators
–
Name: webSphereDefaultIsolationLevel Value: 2
Value: true
Value: 2 Value: 2
47
You may also want to set “accountingInterval” to COMMIT. This setting causes DB2 to create an SMF accounting record every time a COMMIT occurs. This approach greatly simplifies problem determination and resource accounting. On very large systems the additional SMF records may require some additional planning. 17. After you have set the necessary properties, click the Save link in the message at the top of the page.
Define Database Authentication Credentials 18. In the link path at the top of the page, click PegaRULES to return to the PegaRules properties page. Then, under the Related Items section, click the link JAAS – J2C authentication data. You will define your database authentication credentials here.
19. Click New to specify the General Properties.
20. Complete this form as follows: –
In the Alias field enter any name that uniquely identifies this J2C entry.
48
PegaRULES Process Commander Installation Guide v6.1 SP2
–
In the User ID and Password fields, enter the user name and password for the Process Commander database user on your Process Commander database.
21. Click OK to return to the authentication data entries page, and click Save in the Messages section at the top of the page. 22. In the link path at the top of the page, again click PegaRULES to return to the PegaRules properties page.
23. Scroll down to the Security Settings section near the bottom of the page, and in the Component-managed authentication alias dropdown select the J2C alias you just created:
49
24. Click Ok, and then Save in the confirmation message on the Data sources page. 25. On the Data sources page, select the checkbox for PegaRULES and click Test Connection to confirm your data source configuration.
Configure WebSphere WorkManager If you are deploying Process Commander’s EAR archive, prpc_j2ee14_ws.ear, complete the following procedures to define a WorkManager. Process Commander uses the WorkManager to run asynchronous tasks 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 the WorkManger. Continue with the configuration procedure, Other WebSphere Configuration on page 52. 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 select Work Managers
50
PegaRULES Process Commander Installation Guide v6.1 SP2
2. On the Work Managers listing page, set the Scope to the level appropriate for your deployment, and click New.
51
3. Complete the Configuration page for the Work Manager as follows:
52
PegaRULES Process Commander Installation Guide v6.1 SP2
–
In the Name field, enter a name to identify this Work Manager, for example, PRPCWorkManager.
–
In the JNDI name field, enter exactly the JNDI location wm/PegaWorkManager
–
In the Service names section, select the Security checkbox.
–
In Thread pool properties, set Maximum 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.
Other WebSphere Configuration This section contains an additional configuration step you must complete in WebSphere.
Set HTTP transport channel custom property CookiesConfigureNoCache to false In order to support the ability to open files attached to work objects in Process Commander, you must set a custom property, CookiesConfigureNoCache, on the transport chain in the Web Container settings for 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. In WebSphere 7.0, this property is set to True by default so that caching is not allowed. You must create and set this property on the HTTP transport channel for the Process Commander server. For more information see “HTTP transport channel custom properties” in the WebSphere 7.0 Information Center (http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp). Complete the following steps to set this property: 1. In the administrative console, select Servers > Server Types > WebSphere application servers to display the Application servers page:
53
2. Click on the name of your Process Commander server to display the Configuration page:
3. Under Container Settings, expand Web Container Settings, and then click Web Container transport chains. This console displays the listing page for transport chains:
54
PegaRULES Process Commander Installation Guide v6.1 SP2
4. Click the name of the appropriate transport chain: –
If your site is using the default transport configuration for this server, select WCInboundDefault 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.
55
5. Under Transport Channels on this page, click HTTP inbound channel. The console displays the Configuration page for the selected transport channel.
56
PegaRULES Process Commander Installation Guide v6.1 SP2
6. Under Additional Properties on this page, click Custom Properties. The console displays the listing page for this channel’s custom properties:
7. Click New. The console displays the form for a new custom property:
57
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 application Complete the instructions below to deploy the Process Commander core application component prpc_j2ee14_ws.ear.
Important: The Process Commander core application component is available both as a WAR file, prweb.war, or an EAR file, prpc_j2ee14_ws.ear. Pegasystems recommends deploying the EAR file component, prpc_j2ee14_ws.ear for all new deployments on WebSphere 7.0 systems. The WAR file core component, prweb.war, can be successfully deployed on the WebSphere application servers, but deploying and configuring the EAR file ensures that you can add advanced 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.
58
PegaRULES Process Commander Installation Guide v6.1 SP2
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 ignore these messages. You will supply these resources as you complete the installation process. Be sure to stop the application after deploying.
Deploying prpc_j2ee14_ws.ear in WebSphere 1. Ensure that the WebSphere application server is running, and log into the administration console. 2. Under the left frame, select Applications > New Application.
3. Click New Enterprise Application.
59
4. Click the Browse button and navigate to select prpc_j2ee14_ws.ear from your installation media. 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, including the default bindings and resource mappings. 6. Click the ‘ + ‘ sign to expand Choose to generate default bindings and mappings:
60
PegaRULES Process Commander Installation Guide v6.1 SP2
7. Complete this page as follows: –
Select Generate Default Bindings
–
Select Use default virtual host name for Web and SIP modules.
–
Accept the other defaults and click Next:
WebSphere displays the following Security Warning:
8. Scroll to the bottom on this page and click Continue. This security file allows Process Commander to run when J2EE Security Checking is enabled.
Note: To enable J2EE Security for Process Commander, it is necessary to make some site-specific parameter changes in this file. See the J2EE Security documentation for more information. WebSphere displays a wizard in which you can specify installation options:
61
This section of the installation process is a series of 16 steps under the general heading of “Install New Application.” For Process Commander, you only need to make changes in Step 10, Map resource references to resources. For each of the other screens, you may accept the defaults, or customize them according to the requirements of your organization. 9. For Step One, accept the defaults and click Next: 10. Continue through the next steps, either accepting the defaults, or customizing for your organization, as needed. –
In Step 10, you map resource references to resources:
62
PegaRULES Process Commander Installation Guide v6.1 SP2
11. For the three Resource references to url/initialization/explicittempdir, enter the JNDI name url/initialization/explicittempdir in the field Target Resource JNDI Name. There are url/initialization/explicittempdir references for the EJB EngineCMT, EngineBMT and prweb.war. This maps the location you specified in the URL provider you created above to the corresponding Resource Reference in the application, so that the application
63
will use the location for the PegaTempDir. 12. Click Next. Depending on your configuration, you may see a set of warnings related to missing resource references, for example:
These are resource references that are defined in web.xml, the deployment configuration files for the application, but not mapped to resource definitions in your application. In the page, Map resources to references, they are mapped to the Target Resource JNDI Name url/pega/none, indicating that they are not used. Pegasystems provides these references for 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 the requirements of your organization. 15. On the final Summary screen, check the settings, and click Finish:
64
PegaRULES Process Commander Installation Guide v6.1 SP2
The system begins installing the EAR file, which may take a few minutes. The following message is displayed.
65
When the installation completes successfully, WebSphere displays a message similar to the following:
16. Click Save directly to the master configuration.
Installing the System Management and Online Help Applications In addition to the Process Commander application, you must also deploy the online help application (prhelp.war) and System Management application (prsysmgmt.war). Complete the following steps to deploy prsysmgmt.war or prsysgmgt.ear. 1. Under the left frame, select Applications > New Application.
66
PegaRULES Process Commander Installation Guide v6.1 SP2
2. Click New Enterprise Application.
3. Click the Browse button and navigate to select the application war file, prsysmgmt.war or prsysgmgmt.ear, from your installation media. 4. Click Next to begin the installation:
67
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 their defaults. 8. Click Next. You may see some security warnings similar to the following:
68
PegaRULES Process Commander Installation Guide v6.1 SP2
9. Click Continue to pass by the warnings. WebSphere displays the Install New Application wizard:
10. Accept the defaults and click Next for Steps 1 through 7. 11. In Step 8, enter the name of the file, prsysmgmt, as the context root, and click Next.
69
12. On the Summary page, click Finish.
70
PegaRULES Process Commander Installation Guide v6.1 SP2
WebSphere displays a message, Installing . . ., and updates it with information during the install. When complete the following message is displayed in the page:
13. Click the Save link to save the changes to the master configuration. 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. For more details on the System Management Application, refer to the System Management Application Reference Guide.
Assigning the PegaDiagnosticUser Role to your System Management Application Users Users accessing the System Management Application (SMA) in Process Commander must be assigned the role PegaDiagnosticUser. Users can access the SMA in the Process Commander Developer portal by clicking Tools >
71
System Management Application. If the user does not have this role they will be challenged for authentication when they attempt to access the System Management Application from Process Commander. Users can use the SMA to monitor and control caches, agents, requestors, listeners, and other processing in the Process Commander system. Consult the System Management Application Reference Guide for more information. Complete the following steps to set access to the System Management Application. 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.
72
PegaRULES Process Commander Installation Guide v6.1 SP2
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 to Everyone:
73
If you installed the WAR archive, prweb.war, the PegaDiagnosticUser role is set to None:
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 Subjects dropdown to select None.
–
If you want to allow limited access to the SMA, use the Map Special Subjects dropdown to select All Authenticated in Application’s Realm, or click Map Users . . . to assign the role to specific users.
–
If you want to allow open access to the SMA, use the Map Special Subjects dropdown to select Everyone.
5. Click OK, and then Save directly to the master configuration in the Messages box at the top of the Configuration page.
Deploying a Multi-Servant System (Optional) If you are deploying Process Commander in a multi-node deployment with a multi-servant configuration, you must assign a unique temporary directory for each JVM Servant. Multiple Process Commander nodes cannot use the same temporary directory. The following steps outline how to add Java Custom Code for WebSphere in z/OS to assign unique directories for each servant.
1. Define Multi Servant Instances in WebSphere for z/OS 1. In the WebSphere Administration console go to Servers>Application Server>server1>Server Infrastructure> Java Process Management> Server Instances 2. Check on Multiple Instances Enabled 3. Complete the fields as follows: –
Minimum Number of Instances 1
–
Maximum Number of Instances
2. Specify Java Custom Code 1. Go to Application Servers>Servers>server1>Server Infrastructure> Administration>Custom Services. 2. Check on Enable service at server startup
74
PegaRULES Process Commander Installation Guide v6.1 SP2
3. Complete the fields as follows: –
Classname:
com.pega.pegarules.zos.WatchingWLM
–
Display Name: Pegasystems
–
Classpath:
/u/user/przseries.jar
3. Define Java properties for Servant JVM 1. Go to Application Servers>Servers>server1>Server Infrastructure>Java Process Management>Process Definition>Servant>Additional Properties>Java Virtual Machine 2. In the field Generic JVM arguments add or replace the following properties: –
-Dpega.tmpdir=/SYSTEM/tmp/multiServants
–
-Dpega.prefix=TDir pega.tmpdir, /SYSTEM/tmp/multiServants in this example, is the folder where temporary directories will be created by the java Custom Code
4. Enable Security Issue the following commands for the temporay directory folder, for example, /SYSTEM/tmp/multiServants: mkdir /SYSTEM/tmp/multiServants chmod 777 /SYSTEM/tmp/multiservants chown –R ASSR1:WSCFG1 /SYSTEM/tmp/multiServants
5. Provide Disk Space Make sure the HFS segment where folder /SYSTEM/tmp/multiServants is located has enough space. Provide at least 2 Gigabytes or 2000 cylinders.
6. Upload jar file to /u/user/przseries.jar /u/user/przseries.jar was defined in Step 2 above. Issue the following commands: 1.
cd /u/user
2. chmod +rx przseries.jar This Java Custom code creates directories, 01, 02, up to the number of Instances defined in Step 1.and located under ${pega.tmpdir} defined in Step 3 above. The full name of the Temp Directory is ${pega.tmpdir}/${pega.prefix}01, for example:
75
/SYSTEM/tmp/multiServants/TDir01 The Java Custom Code manages the status of Temporary Directory assignment with files: –
/SYSTEM/tmp/multiServants/Synch
–
/SYSTEM/tmp/multiServants/TDirxx/lockedFile.fil
These files have no data. They are created during WebSphere sessions and should not be removed. The Java Custom Code prints a short report, for example: * CustomCode * nodeName:PEGN * CustomCode * serverName:server1 * CustomCode * ServerPid:0000033800000056 * CustomCode * JOB Name:BBOS001S * CustomCode * JES2 ID:STC08496 * CustomCode * Unix PID:224 * CustomCode * MVS ASID:206 * CustomCode * property pega.tmpdir=/SYSTEM/tmp/PegaTmpDirV53//TDir02
Maintaining a unique PegaRULES log file for each Servant. You can redirect the PegaRULES log file for each Process Commander node to the Temporary Directory, for example: /SYSTEM/tmp/multiServants/TDirxx/PegaRULES-2007-Aug-28.log /SYSTEM/tmp/multiServants/TDirxx/PegaRULES-ALERT-2007-Aug-28.log
To redirect the log files, update the prlogging.xml file for each deployment for the PegaRULES log file and PegaRULES-ALERT: 1. Replace:
with:
2.
Replace:
Customizing PegaRULES log file names using MVS properties The Java Custom Code also creates three new user properties: –
%procid
process id number or pid
–
%jname
job name
–
%jnumber
job number
You can also include these properties in the entries for the log and alert files in prlogging, as shown below:
