PegaRULES Process Commander Release V6.1 SP2 Installing on JBoss Application Server— Community Edition (jboss.
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.
Contents Introduction..................................................................................................................................... 1 Process Commander Deployment Architecture ............................................................ 1 Overview of the Installation Procedure ................................................................................. 3 Process Commander Core Component Versions ................................................................
iv Pegarules Process Commander Installation Guide V6.1 SP2 Deploying the Online Help Application ............................................................................... 24 Assigning the PegaDiagnosticUser Role to your System Management Application Users ................................................................................................................................................ 24 Next Steps .........................................................................................
Introduction This document describes how to install a new instance of PegaRULES Process Commander 6.1 SP2 on JBoss Application Server—Community Edition (jboss.org) 4.2.2. Note: A separate Installation Guide is provided for installing Process Commander on the JBoss server distributed with the Red Hat Enterprise Application Platform. For installing on the Red Hat platform, see Installing on JBoss Application Server—Red Hat EAP 4.3.
2 PegaRULES Process Commander Installation Guide v6.1 SP2 such as database connections, Java Messaging Services (JMS) support, and connector and services interfaces to other external systems. 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.
4 PegaRULES Process Commander Installation Guide v6.1 SP2 ■ Step 2: Database Preparation, page 9. Create and configure a blank 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.
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. PRPC Configuration Phase You complete the PRPC 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 41.
6 PegaRULES Process Commander Installation Guide v6.1 SP2 Step 1: Environment Considerations 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.
7 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.
8 PegaRULES Process Commander Installation Guide v6.1 SP2 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 A Note for PRPC 4.2 Users This installation procedure differs from earlier installation procedures in significant ways.
9 Step 2: Database Preparation To prepare your database server to use with Process Commander, you must complete the following tasks: ■ Create a blank database. ■ Create an appropriate user that Process Commander can use to access the database. ■ Create a database schema that defines the data objects (tables, indexes, views, triggers and procedures) required by Process Commander.
10 PegaRULES Process Commander Installation Guide v6.1 SP2 Install and configure the relational database according to vendor directions. This database may reside on the same server as the Process Commander software, or it may be on a different server. Creating a PRPC Database Create a database with a minimum of 4GB for the user tablespace and allow the database to grow. For a typical development environment, expect the database to grow to at least 10GB over time.
11 To implement two users, you configure access to the database in your application server by creating two data sources: ■ One datasource referencing the JNDI location jdbc/PegaRULES that specifies the username and password for the base DB user. This user must have at least read and write permissions for the database. ■ A second datasource referencing the JNDI location jdbc/AdminPegaRULES specifying the username and password for the DB Admin user.
12 PegaRULES Process Commander Installation Guide v6.1 SP2 User Privileges for the Oracle Database Set the user account for the Process Commander database user with the default RESOURCE and CONNECT roles with all corresponding system privileges granted. In particular, be sure that the user has the Create View system privilege. Note: On the Oracle 10g HTML-based Enterprise Manager console there are separate tabs for setting the user’s roles and system privileges.
13 Using a SQL Script to Create the Schema If you choose not to select the Create Schema option in the Installation and Upgrade Assistant your database administrator (DBA), or someone with appropriate permissions, must run a SQL script to create the schema in your Process Commander database. 1. In the software distribution directory for Process Commander find the install SQL script for your database type. C:\PRPC_distro\schema\oracledate\install\oracledate_install_6.1SP2.sql 2.
14 PegaRULES Process Commander Installation Guide v6.
15 1. Confirm that the Java JDK environment used by your application server is Java JDK 1.5.0_07 or higher. 2. Confirm or set a JAVA_HOME environment variable to point to the directory where Java is installed. 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. Verify the JBoss Environment 1.
16 PegaRULES Process Commander Installation Guide v6.1 SP2 – If your application server is using the Sun JVM, add the PermSize and MaxPermSize settings as well: – • –XX:PermSize=64m • –XX:MaxPermSize=384m Append the command -Djava.awt.headless=true to the JAVA_OPTS values. You must add the “headless” AWT setting to the JAVA options to allow the system to render graphics. PRPC requires this setting in order to display graphical reports.
17 Set up default Pega credentials for the server Complete the following procedures to provide the default credentials that match the JBoss specific deployment descriptors shipped with PegaRULES. This is necessary to avoid exceptions during EJB deployment. Edit conf\login-config.xml 1. Open the file $JBOSS_HOME/server/pega/conf/login-config.xml in a text editor. 2. Search for '"other"' (with quotation marks) 3.
18 PegaRULES Process Commander Installation Guide v6.1 SP2 pegatest=pega0123 3. Save and close the file. 4. Create a text file named roles.properties. 5. Enter a property that assigns the PegaAuthUser role to the pegatest user: pegatest=PegaAuthUser 6. Save and close the file. Note: By default, the PegaAuthUser role is not required for users accessing Process Commander. If you want to implement container-managed authentication, you assign the role to your users using the users.properties and roles.
19 For both SQL Server 2005 and 2008, use the appropriate driver for your JVM – For Java 5: sqljdbc.jar – For Java 6: sqljdbc4.jar Oracle Use the drivers provided by your application server or download the latest drivers from the Oracle website. The appropriate file depends on the version of your JVM: – For Java 5: ojdbc5.jar – For Java 6: ojdbc6.jar If you are using the OCI (thick) driver, this directory must also contain the Oracle Client software.
20 PegaRULES Process Commander Installation Guide v6.1 SP2 jdbc:microsoft:sqlserver://:1433;SelectMethod=cursor;SendString ParametersAsUnicode=false;DatabaseName= com.microsoft.sqlserver.jdbc.
21 – If you are using Java 5 and the ojdbc5.jar driver file, add a connection property element defining the property oracle.jdbc.V8Compatible=true. For example: true Note: If you are using Java 6 and the ojdbc6.jar driver file, the V8Compatible setting is not required. UDB jdbc:db2://[hostname]:[port]/yourdatabase – Replace [hostname] with the hostname of your database server.
22 PegaRULES Process Commander Installation Guide v6.1 SP2 – SQL Server 2005 and 2008: com.microsoft.sqlserver.jdbc.SQLServerDriver 4. In the user-name and password elements, enter the user name and password for the account you created for your Process Commander database. 5. In the type-mapping element, enter your database type: – Oracle 10g, 11g: Oracle9i (Applies to 9i and later. Make sure that you have the latest Oracle 10g version of ojdbc14.
23 # jar -xvf prweb.war Specify explicit temp directory in prconfig.xml 1. In the application directory, open the Process Commander configuration file, $JBOSS_HOME/server/pega/deploy/prweb.war/WEBINF/classes/prconfig.xml. 2. Find the env element for the temporary directory: 3. Replace $(pega.
24 PegaRULES Process Commander Installation Guide v6.1 SP2 # mkdir prsysmgmt_jboss4 3. Copy the application archive, for example prsysmgmt_jboss4.war, to the directory: # cp /PegaRULES/archives/prsysmgmt_jboss4.war $JBOSS_HOME/server/pega/deploy 4. Extract the application archive into the folder. # jar -xvf prsysmgmt_jboss4.war For more details on the System Management Application, refer to the System Management Application Reference Guide.
25 Note: Changing this setting in the web.xml file may require redeployment of the PegaRULES Web Application. If you want to restrict access to the System Management Application, edit the users.properties and roles.properties files to assign the PegaDiagnosticUser role to any users that must be able to access the System Management Application. For information about creating the users.properties and roles.properties files, see “Create users.properties and roles.properties files” on page 17.
26 PegaRULES Process Commander Installation Guide v6.1 SP2 Steps 4 – 9: Rulebase Setup Install the Process Commander Schema and Rules in the Database Run the Process Commander Installation and Upgrade Assistant to create the Process Commander schema 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 the database and load the base Process Commander rules. The 6.
27 1. Use a 32-bit JVM to run PRPC_Setup.jar, or 2. Increase the memory allocated to the JVM: – In the scripts directory of your Process Commander software distribution, open the file setupDatabase.xml in a text editor. – In the file find the following element: – Increase the value of –Xmx to 2048. – Save and close the file 2. Extract PRPC_DistributionImage.
28 PegaRULES Process Commander Installation Guide v6.1 SP2 In this case, use the command-line jar command as described above. 4. Click Next to display the Environment Considerations. See “Step 1, Environment Considerations in this guide for more information on completing this step. 5. Click Next to display the Database Preparation page.
29 6. 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 this step. These tasks are completed outside of the Assistant. You must complete this preparation before running the Rulebase Load phase. You can exit from this tool to complete them, and then restart to continue beyond this point. 7. When your Database Preparation is complete, click Next to display Application Server Preparation.
30 PegaRULES Process Commander Installation Guide v6.1 SP2 8. Review this page to learn about the tasks you complete to prepare your application server before deploying the Process Commander applications. These tasks are completed outside this Assistant. You can exit from this tool to complete them, and then restart to continue beyond this point, or you can continue with the Rulebase Setup phase immediately and complete the Application Server Preparation later.
31 9. If you have completed your Application Server Preparation or you want to continue with the Rulebase Setup in the database before completing the Application Server Preparation, click Next to display the License Agreement. 10. Review the License agreement and click Accept to continue.
32 PegaRULES Process Commander Installation Guide v6.1 SP2 11. Select Installation and click Next to display the Database Configuration page. 12. Complete this page as follows: Database Type – Select the type of your Process Commander database. Note: Instructions to install using a database on DB2 on z/OS are not covered in this guide. See the Installation Guide for DB2 on z/OS and WebSphere for information on this platform.
33 Click Next to display the Database Connection page. If your database type is Oracle or MS SQL, you specify the JDBC driver class name, the location of the driver JAR file, the database connection URL, and the database user name and password.
34 PegaRULES Process Commander Installation Guide v6.1 SP2 13. Complete the fields to specify the database connection to your Process Commander database: – JDBC Driver Class Name – Enter the name of the appropriate database driver class: • Oracle 10g/11g: oracle.jdbc.OracleDriver • IBM DB/2 Type 4: com.ibm.db2.jcc.DB2Driver • SQL Server 2005 and 2008: com.microsoft.sqlserver.jdbc.
35 – UDB Schema Name—For UDB databases, enter the schema name assigned to the Process Commander database when it was created. 14. When you have completed entering the database connection information, click Test Connection. The Installation Assistant tests whether it is able to make a connection to the database you have specified and displays the result: Click OK to close the window. If the connection is not successful, review your connection information, correct any errors, and retest.
36 PegaRULES Process Commander Installation Guide v6.1 SP2 directory to grow to this size. The Assistant deletes all temporary files at the end of the process. – Click Next to display the Rulebase Loading page. 16. Press START to begin loading the database with the rules.
37 Click Show Logs to see the log detail as the process is running. The Assistant displays the following window when complete: Note: A typical installation can take 20 to 60 minutes depending on the speed of your system. If you choose to pre-load the assembled rules cache, the process takes an additional 90 minutes.
38 PegaRULES Process Commander Installation Guide v6.1 SP2 When processing the larger files, the log can appear inactive for some minutes. Please allow the Assistant to finish. 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.
39 18. Click Exit in the Assistant and continue with the procedures in the next section “Step 10—Final Settings in PRPC.
40 PegaRULES Process Commander Installation Guide v6.1 SP2 Step 10: Final Settings in Process Commander Access the Process Commander servlet, PRServlet, through a browser. Type in the URL for Process Commander application: http://://PRServlet.
41 Login to Process Commander: – User Name: administrator@pega.com – Password: install The Process Commander Developer portal displays with a welcome message in the What’s Happening section of thepage: Process Commander automatically launches a process to index the Process Commander rules in the system to support full-text search in the Developer environment. While this process is running, you may notice some delay in the responsiveness of the Process Commander user interface.
42 PegaRULES Process Commander Installation Guide v6.1 SP2 Enable Developer Help and the System Management Application To enable Help and the System Management Application, you must set the URLs that are used to access them. 1.
43 2. Complete this page to specify the URLs to access the Help (prhelp.war) and System Management (prsysmgmt_jboss4.war or prsysmgmt_jboss4.ear) applications – In the field Online Help URL, enter the URL for the prhelp.war file: Provide the name of your Process Commander server and the port number, for example, http://prpc_server:8080/prhelp – In the field for SMA URL, enter the URL for the System Management Application, for example, http://prpc_server:8080/prsysmgmt.
44 PegaRULES Process Commander Installation Guide v6.1 SP2 2. In the Organization Name field, enter the name of your organization, leave the Action control 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.
45 Create a Systems Management Node Identify a node for your Process Commander system in Pegasystems’ System Management application to enable monitoring of the installation. For more details on the System Management Application, refer to the System Management Application Reference Guide available on the Pega Developer Network (http://pdn.pega.com). 1. Login as an Administrator. 2.
46 PegaRULES Process Commander Installation Guide v6.1 SP2 The System Management Console opens. No nodes are set up initially. 3.
47 4. Complete this form by entering the information appropriate to your installation of Process Commander. You must complete all required fields. The example values above show the basic configuration for a Process Commander instance on the same server as the prsysmgmt_jboss4.war application. You can also use this application to connect to remote instances of Process Commander by supplying the appropriate information for the remote server machine. 5.
48 PegaRULES Process Commander Installation Guide v6.1 SP2 6. To view data on this node, click the host name, in this case localhost, in the navigation pane on the left.
49 For information on all the functionality of the System Management Application, refer to the System Management Application Reference Guide available on the Pega Developer Network (http://pdn.pega.com). Click PRPC System Tools in the navigation menu on the left of the PDN home page to find a link to the guide. Install Solution Frameworks If you are installing one of Pegasystems Solution Frameworks as part of your Process Commander development environment, install the framework now.
50 PegaRULES Process Commander Installation Guide v6.1 SP2 Ap p e n d ix A: Command-line Interfaces for Installation and Upgrade Process Commander 6.1 SP2 provides a command-line interface for installing or upgrading Process Commander databases. You can call t mander Schema and Database This section describes the command-line interface to the Process Commander Installation and Upgrade Assistant. To install the Process Commander database, you 1. Create a database using your DB vendor's tools 2.
51 1. Use your database tools to run SQL scripts that Pegasystems provides to update the database schema 2. Specify the database connection information in the setupDatabase.properties file. 3. Run upgrade.bat or upgrade.ksh to update the Process Commander rules and classes Note: Executing upgrade.bat or upgrade.ksh does not update the database to the 6.1 SP2 schema. You must apply the SQL scripts provided by Pegasystems to your Process Commander database before running the upgrade script.
52 PegaRULES Process Commander Installation Guide v6.1 SP2 – pega.jdbc.driver.jar= The full path to the JDBC driver file for your database The driver required for each database type is: Oracle 10g/11g: • For Java 5: ojdbc5.jar • For Java 6: ojdbc6.jar DB/2 UDB: db2jcc.jar SQL Server 2005,2008: – • For Java 5: sqljdbc.jar • For Java 6: sqljdbc4.jar. pega.jdbc.driver.class= The class name of the JDBC driver for your database. The class required for each database type is: Oracle 10g/11g: oracle.
53 jdbc:sqlserver:// :1433; databaseName=;SelectMethod=cursor; SendStringParametersAsUnicode=false; Note: Be sure to include the SelectMethod and SendStringParametersAsUnicode parameters for SQL Server. – pega.jdbc.username= pega.jdbc.password= The user name and password to use when connecting to your database. – user.temp.dir= The full path to a temporary directory for the script process to use while loading the Process Commander rules.
54 PegaRULES Process Commander Installation Guide v6.1 SP2 Running the Install and Upgrade Scripts After entering the settings in setupDatabase.properties, run the appropriate install or upgrade script for your platform: ■ install.bat for Windows, install.ksh for Unix systems ■ upgrade.bat for Windows, upgrade.ksh for Unix systems You can pass up to six arguments to either script to override the properties set in the setupDatabase.properties file.
55 Notes: If you wish to use configuration files, you must create both files and set the corresponding properties. If either of the properties is not set, the script will generate both configuration files. You must always set the "pega.jdbc.driver.jar” property in setupDatabase.properties. Neither prconfig.xml or prbootstrap.properties contains the location of the DB driver file. – bypass.load.engine.classes If set to any value, the Rules Engine classes are not loaded into the database.
