Installing PegaRULES Process Commander (PRPC) 6.3 SP1 on CentOS 7David J. Walling, March 13th, 2017Email: david@davidjwalling.com

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 administrator@pega.com 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.