Installing PegaRULES Process Commander (PRPC) 6.3 SP1 on CentOS 7David J. Walling, March 13th, 2017Email: [email protected]
This “how to” describes how to install and configure the PegaRULES Process Commander (PRPC) version 6.3 SP1 Business Process Management (BPM) software on CentOS 7 with Apache Tomcat using Oracle XE 11g.
To complete this installation, we will need to define the PRPC database schema, update our Java and Tomcat configuration, and load the database with an initial “rulebase”. These steps can take several hours to complete. We will take care of some of the less time-consuming tasks up-front.
As a first, step, locate the PRPC installation archive. PRPC is a licensed product that is available from Pegasystems, Inc. Here we can see the compressed archive for PRPC version 6.3 SP1.
The first installation step we take may seem strange. But, we need to open the .zip archive (not expanding it) and extract only one file here on our host OS. The file we need is the SQL DDL (data definition language) script to define the database tables for PRPC 6.3.
Double-click on the .zip archive to open WinZip, 7-Zip or whatever data compression tool you have installed on your host. Then, navigate into the archive to locate the file “oracledate_install_6.3SP1.sql” located in the schema/oracledate/install folder.
Once, you've located the file, drag it to the Downloads folder, or wherever you have the compressed archive stored, in order to extract the file from the archive.
In a prior “how to” in this CentOS series, we installed and configured Oracle XE 11g. Part of that configuration included creating a PEGA schema in the database. Now, we will run the extracted SQL DDL to define tables and views in the PEGA schema.
In our previous “how to” in this series, we updated our CentOS 7 virtual machine by adding the Gnome graphical user interface (GUI) and desktop. We'll use that environment for part of our installation process. So, if you're CentOS 7 virtual machine is not running, start it normally so that you have a session window. You do not need to log in yet.
We've configured our CentOS VM to automatically start SSH, Oracle and Tomcat. So, even without logging in, we should be able open a browser on our host and navigate to the Oracle Apex application running on our CentOS guest.
Open a browser and navigate to our CentOS guest. In this example, the address is:
http://192.168.1.7:8521/apex/f?p=4550:1
Note that throughout these “how to” documents, the IP address for our guest OS changes, depending on where the host computer is actually connecting to the Internet.
On the Apex logon screen, enter the Workspace (schema) user name and password we set up in an earlier “how to”. In case you've forgotten, we have the PEGA user the password “rules”.
After logging in to Apex, we want to open the “SQL Workshop” tool. Click on the “SQL Workshop” toolbar icon.
Within the SQL Workshop, we select “SQL Scripts”. Note that we can navigate through Apex using either the toolbar icons or using the menu bars as shown above.
On the SQL Scripts page, click the “Upload” button to open the “Upload Script” dialog.
In the “Upload Script” dialog, first click the “Browse” button, navigate and select the PRPC SQL DDL file that we extracted from the installation archive. The screen capture above shows the name of the file and how it is displayed after it is selected.
When the .sql file is selected, click the “Upload” button.
After clicking, upload, Apex will upload the SQL DDL script. The number of bytes is shown in the dialog. It should be 338,405. Check the check-box on the left hand side of the row where the script is displayed. Then, click on the “Run” icon, which is styled to look like a traffic signal.
Apex will parse the script and then display a dialog showing how many SQL statements were found in the script.
The SQL DDL script to install Pega PRPC 6.3 SP1 should contain 388 statements. Confirm this number. If the number is correct, click the “Run Now” button. This will run the script. The web page may take upward to a minute to complete.
When the script has completed, a result screen will be displayed.
The “Status” column of the result screen should read “COMPLETE”. The “Statements” column should indicate that all 388 of the statements were executed. You can click on the icon on the row for the script in the “View Results” column to see more detailed results.
The report shown by the “View Details” icon has both a “Summary” and a “Detail” mode. Inspect both at your leisure. However, so long as all 388 statements completed successfully, we have completed the database schema part of the PRPC installation.
Log out of Apex (Oracle Application Express) and close the browser.
If you want to confirm the output of our SQL DDL using a separate tool, remember that we used DbVisualizer in an earlier “how to” to establish and demonstrate connectivity to our Oracle XE instance running on CentOS. We can use this tool again to view the table objects created by running our SQL DDL script.
After confirming that you can connect to the PEGA schema in the Oracle database using DbVisualizer, you can close DbVisualizer.
Now we will proceed to the next installation step to update our Java configuration.
Just like we did in earlier “how to” articles, we use FileZilla to upload the installation archive file to our CentOS virtual machine using our administrative user login.
Once we've uploaded the archive, log into CentOS as the “root” user, using the Gnome GUI and open a terminal window. We're using “root” because we will have to move some files between user folders. Also, the “rulebase” load step must be run as the “root” user.
As “root”, change the current folder to /home/tomcat. Move the installation archive file from our administrative user's home folder and change the file's owner and group to “tomcat”. Then “su” to change our current user to “tomcat” and unzip the archive.
Once the archive is unzipped, we exit the “tomcat” bash shell back to the “root” session.
As “root”, but in the “tomcat” user home folder still, we create an “endorsed” folder in the Java “lib” folder and copy one .jar file into it. This is an update to the JAX-WS API to version 2.2.5.
And that is the only Java configuration change we need to make. Next, we have some Tomcat configuration changes to make.
In a previous “how to”, we installed Tomcat 7. But we did not create a “setenv.sh” script, which we now need. Create the file to contain a single line as shown below.
And set the appropriate permissions to make the script executable.
Next, we update the /usr/local/tomat/conf/server.xml file as “tomcat”. We add only one setting, enableLookups=”true”, to the connector definition for port 8080. This is required so that the Pega Tracer tool can perform DNS lookups.
To edit the file, use the command “vi /usr/local/tomcat/conf/server.xml”.
Save these changes and exit the editor.
Next, we will edit the /usr/local/tomcat/conf/context.xml file as “tomcat”. We will add a Resource definition and an Environment definition to the existing Context. The Resource will define our connection to the Oracle database. The Environment will define our temporary directory for PRPC caching.
You want to choose a location for the PRPC temporary directory that has at least 6GB of available disk space.
After editing the context.xml file, make sure you create the PRPC temporary folder as user “tomcat”.
Now, we've made the necessary changes for tomcat. So we will restart the tomcat service.
Now we we will populate the Oracle tables with the PRPC “rulebase”. This is time-consuming process. We must run this process as “root”. To begin, execute the “PRPC_Setup.jar” file using java.
# java -r PRPC_Setup.jar
We will use the PegaRULES setup application. Click “Next” through the first few information screens until you are prompted to accept the license terms.
Click the “Accept” button on this screen.
On the next screen, keep “Installation” checked and click “Next”.
On the “Database Type” screen, select the “Oracle Database” radio-button, uncheck the “Create Database Schema” check-box (we've already created the schema), and check the “Bypass UDF Schema Generation” check-box.
Click the “Next” button when you have these settings set correctly.
On the next screen, enter or confirm the Database connection settings.
JDBC Driver Class Name: oracle.jdbc.OracleDriverJDBC Driver Jar File: /usr/local/tomcat/lib/ojdbc6.jarDatabase JDBC URL: jdbc:oracle:thin:@192.168.1.7:1521/XEDatabase Username: pegaDatabase Password: rulesSchema Name: PEGA
When you enter the Database Connection settings and click the “Test Connection” button, you should see the message shown above. Click “OK” to close the dialog. Then, click “Next” to proceed.
On the following screen, leave the System Name as “pega” and the “Production Level” as 2. Note that the “Temporary Directory for this Tool” is NOT the same as the “/tmp/pegatemp” folder we created for use by PRPC. The directory shown on the screen above is only for use by the installation process. Leave this value unchanged.
On the next screen, there is a “START” button. Click this button to being the “rulebase” load. This will begin the process of loading the Oracle database with initial values required to run PRPC. This could take well over an hour depending on the speed of your system.
To follow the progress in more detail, click the “Show Logs” button.
When the rulebase load completes successfully, a pop-up window will appear notifying you of the completion. The output log indicates success and the total duration.
Now, with the database populated with the initial rulebase, we will deploy the PRPC application WAR and provide some final configuration.
To deploy the PRPC WAR, we launch a browser on our host OS and connect to our Tomcat service running on our Guest OS. Before doing this, however, unzip the PRPC installation archive on the Host OS.
Click on the manager webapp link and login using the tomcat user and password that we defined in an earlier “how to” when we edited the tomcat-users.xml file.
Scroll down tot he “Deploy” section of the manager web screen. Here, you can click the “Browse” button to navigate into the “archives” folder and select the prweb.war file.
Click the “Deploy” button when the “prweb.war” file is selected. This action will take a few minutes to complete.
After deploying prweb.war, also deploy the prsysmgmt.war and prhelp.war. When these .war files are deployed, the “Applications” section of the Tomcat manager screen will be updated to include them.
With the .war files deployed, we have three more edits to make to configuration files created during the deployment process.
First, stop the tomcat process and remove the prweb.war, prsysmgmt.war and prhelp.war from the /usr/local/tomcat/webapps folder.
The first configuration edit will be to update the output location of log files. These settings are defined in the prlogging.xml file in the folder /usr/local/tomcat/webapps/prweb/WEB-INF/classes.
We will prepend the value for each log appender to direct the logs to the /usr/local/tomcat/logs folder. Update appenders named “PEGA”, “ALERT”, “BIX”, “ALERTSECURITY”, and “SERVICES-PAL”.
The screen capture below shows the first three of these appender definitions updated.
The second edit we will make is to allow SMA to access database connection details, requestor details and the clipboard. The file we will edit is:
/usr/local/tomcat/webapps/prweb/WEB-INF/classes/prmbeans.properties.
Now, we can restart the Tomcat service. Once the Tomcat service is restarted we can launch a browser and open the PRPC development portal.
To launch the development portal, you must use a browser version that is supported by PRPC 6.3 SP1. Here, I've installed a VirtualBox VM with Windows 7 using IE 8.
Navigate to http://192.168.1.7:8080/prweb/PRServlet after opening IE 8.
Login with the User ID “[email protected]” and the Password “install”.
After logging in, the Developer portal will be displayed. Note that the developer portal in PRPC 6 requires the installation of several ActiveX controls on the workstation. The first time you log in, this process may take several minutes to approve of and install all controls. Once all controls are successfully installed, the developer portal should appear as above.
