Accessing Pega 7 Tomcat Admin Console for Personal Virtual Server Installations

When Pega is installed as a Personal Virtual Server, using VMWare (as per the Exercise Systems on Pega Academy), the Tomcat web server’s manager application (aka admin console) can be accessed from the host operating system. In this post, it is shown how to do that for Pega 7.1.6 and Pega 7.1.9.

Summary

  1. Start the Virtual Machine and Confirm that Designer Studio is Accessible
  2. Obtain IP Address of the Virtual Machine
  3. Accessing the Tomcat Manager Web Application

Related Posts

1   Start the Virtual Machine and Confirm that Designer Studio is Accessible

  • Use the VMWare Player to start the virtual machine. Click on the desired virtual machine and then click on the link Play virtual machine. It may take a few minutes for the virtual machine to start.

VMWare Player Play virtual machine

  • By default, the Designer Studio will be accessible through the URL:

Pega 7 Login Verify that Pega Designer Studio is Accessible

2   Obtain IP Address of the Virtual Machine

  • Note: If the Designer Studio is not reachable using the prpc hostname, the IP address of the virtual machine can be used instead.
  • Open the VMWare command line window and press enter to log into the virtual machine.
  • For the Pega Exercise System installations, use the following login credentials:
Pega 7.1.6: username = architect and password = password
Pega 7.1.9: username = root and password = install
  • On the command line, execute the command below to view the virtual machine’s IP address.
ifconfig -a
  • Here, the IP address is 192.168.5.129.

Lookup Virtual Machine IP Address from VMWare Player Command Line using ifconfig

  • Then use it to access the Designer Studio.

3   Accessing the Tomcat Manager Application

  • The Tomcat manager application will be accessible through the URL:
  • By default, the Tomcat manager application is protected by HTTP basic authentication (BA) and a dialog window will appear that requires entering a username and password.
  • The default Tomcat manager application credentials are:
username: admin
password: password

HTTP basic authentication for Tomcat admin console (use admin, password)

  • The Tomcat manager application lists three Pega related web applications:
prhelp – The Pega Help System
prsysmgmt – The Pega System Management Application (SMA)
prweb – Pega PRPC, Designer Studio and Case Manager Portals

Tomcat admin console aka Tomcat Web Application Manager

  • Use the Start and Stop buttons to e.g. restart the prweb Pega PRPC application.

Example of FTP Connection to Pega 7 PRPC for Private Virtual Server Installations

When running on a virtual machine as the Pega Exercise System, the PRPC 7 file system can be accessed using an FTP client application such as FileZilla to exchange files between the host system and the virtual machine.

Summary

  1. Access the Virtual Machine running Pega 7 to Confirm that SFTP Server is Running
  2. Using FileZilla FTP Client to open a Connection to the Pega 7 Virtual Machine
  3. Obtaining the IP Address of the Pega 7 Virtual Machine

Related Posts

  • The Pega 7 Exercise System personal virtual server (PVS) is based on a virtual machine that uses Ubuntu as the operating system by default.
  • Open the VMWare Player and click on the virtual machine name that you want to use.
  • Then click on the link Edit virtual machine settings to review the network settings of the virtual machine.

VMWare Player Edit - virtual machine settings

  • Clicking on Network Adapter will open a view showing the current network connection settings.
  • In this example, the virtual machine is configured to use Host-only so that the virtual machine will be using an IP address in a 192.168 private network with the host operating system.

VMWare Player - Virtual Machine Settings - Network Adapter

  • Click on the Play virtual machine link to start the virtual machine and use the VMWare Player to access the command line. The default login credentials for pega 7 are:
Pega 7.1.6: username = architect and password = password
Pega 7.1.9: username = root and password = install

VMWare Player - Ubuntu Virtual Machine Command Line Login

  • The following command can be used to confirm that the SFTP service is running.
netstat -nltup | more
  • By default, the SFTP service should be running.

VMWare Player - Ubuntu Virtual Machine SFTP Run netstat command

  • A list of active TCP connections will be shown. Look for the one where the port shows 22 and the state shows LISTEN.
  • The IP address 0.0.0.0 indicates that the FTP server is reachable at all of its IP addresses (if it has multiple interfaces).

VMWare Player - Ubuntu Virtual Machine - Confirm FTP Server is running

  • To further confirm that the SFTP server is running properly and that the architect/root users can be used to open a connection, run the following command:
sftp [email protected]
Pega 7.1.6: username = architect and password = password
Pega 7.1.9: username = root and password = install

VMWare Player - Ubuntu Virtual Machine SFTP Confirm Localhost Connection

  • To close the SFTP connection and to exit the program, enter: quit.

  • The FileZilla client for Windows and Mac can be downloaded for free from the source below.
  • Install the client and the run it. Navigate to File > Site Manager and add a new site by clicking on the New Site button.
  • Enter the SFTP connection parameters as shown below.
Host: prpc or IP address, here 192.168.241.128
Port: 22 or blank for default, which is 22 for SFTP
Protocol: SFTP - SSH File Transfer Protocol for secure FTP over SSL
Logon Type: Normal …with username and password
User: architect for 7.1.6 or root for 7.1.9
Password: password for 7.1.6 or install for 7.1.9

FileZilla - Site Manager Create New Site

  • Click on the Connect button to open the connection.
  • A message may appear, asking if the server SSL certificate should be trusted. Click on Yes to continue.
  • FileZilla can now be used to navigate the file system of the virtual machine and to copy files to and from the host operating system.

FileZilla - Access Pega PRPC File System on Virtual Machine Ubuntu

  • Note: FileZilla can also be used to set file permissions. Right-click on a directory or file and select File permissions from the context menu.

FileZilla - Context Menu Change File Permissions

  • The dialog can be used to set read, write and execute permissions for owners, groups and public.

FileZilla - Change File Attributes

  • Note: If the Designer Studio or the FTP server are not reachable using the prpc hostname, the IP address of the virtual machine should be used instead.
  • Open the VMWare command line and log into the virtual machine. For Linux based PVS, execute the command:
ifconfig -a
  • In this case, the IP address that is used by the PVS virtual machine is 192.168.241.128.

VMWare Player - Ubuntu Virtual Machine Run ifconfig to get IP Address

  • From the Windows or Mac host machine, confirm that the virtual machine is reachable by the given IP address.
  • On Windows, open a command line window by clicking on the Start icon and entering cmd in the text box of the Windows menu.
  • The cmd program should be listed at the top of the list under Programs.
  • In the cmd window execute the ping command using the ip address that was obtained from the VM command line using the ifconfig command. Here it is, 192.168.241.128.

Windows 7 Command Line Ping Ubuntu Virtual Machine

  • If pinging the virtual machine was successful, continue with section 3 below. If not, it may be necessary to change the network settings of the VM in the VMWare Player (…NAT, Bridged).
  • In addition, make sure that there are no firewall issues on the host machine.
  • If the host machine is in a VPN, this could also cause problems with resolving the IP address of the VM.

Example of Pega 7 File Service and File Listener to Parse CSV Files and Insert Rows into Data Table

This post shows how a Service and a File Listener rule can be used to automatically populate a data table based on an input text file (comma-separated values). During processing, the delimited text file is parsed and for each row, a record is created in the target data table. This setup saves manual labor when large input files are used to populate data tables.

Related Posts

Summary

  1. Setup of Data Table in Pega 7 and Description of CSV File Format
  2. Creating the Service Rule using the Pega 7 Service Accelerator
  3. Implementing the Service Rule to Parse and Process CSV Files in Pega 7
  4. File Listener Configuration in Pega 7
  5. Running the File Listener
  6. Move CSV Files to Source Location and Run File Listener and Service in Pega 7

In this example, an existing data table for a class named ABC-Insurance-Data-Adjuster is populated automatically. The data table serves as a reference for claims adjusters that are contracted for investigating insurance claims. This class has the following properties:

ID of type Identifier
Firstname of type Text
pyLabel of type TextPega standard property will be used for the last name
HourlyRate of type Decimal
PhoneNumber of type Text
  • The screen shot below shows the configuration page when this data table was created using the Data Table Wizard.
  • Note that the check box CREATE DEDICATED DATABASE TABLE? is checked so that this static reference data can be migrated with the application.

Pega Data Table Wizard - Create New Data Table

  • Initially, there is no data in the data table and the row count shows 0 in the data table view.

Pega 7 Designer Studio - Data Model - Show Data Tables

  • The gear icon in the Edit column can be used to manually insert instances.
  • However, in this example, a Service and File Listener rule are used to automatically insert instances from a sample CSV text file shown below.

Example CSV File adjusters.csv

  • Each delimited row in the file represents a claims adjuster (a person that reviews an insurance claim).
  • The structure of the rows must match the properties defined in the data table into which instances will be inserted.
  • In addition, the input file has a header row where the fields match the property names of the class of the target data table.

A Service rule needs to be created. This rule will read and parse the input CSV file(s) and then use an activity to insert instances into the specified data table for each input row.

  • Navigate to Designer Studio > Integration > Services > Service Wizard to open the Service Accelerator tool.

Pega 7 Designer Studio - Accessing the Service Wizard

Step 1: Select Service Purpose

  • Select Process input or output data for the Service purpose and File for the service type, then click the Next button.

Pega 7 Service Accelerator (Service Wizard) - Select Service Purpose

Step 2a: Provide Service Details – Select Data Class

  • This step requires the selection of the appropriate data class, i.e. the class name of the data table into which instances will be inserted.
  • In this case, the data class is ABC-Insurance-Data-Adjuster. The service name in this example is InsertAdjusters and the wizard will use this name for the generated Service.
  • Click on the Next button to continue.

Pega 7 Service Accelerator (Service Wizard) - Provide Service Details and Select Data Class

Step 3: Customize Service Data

  • This step is used to define the primary input and output properties. Click on the two check boxes labeled Select FIELD NAME in the Primary Page Input Properties and Primary Page Output Properties sections.
  • The property pyLabel is not listed here since it is inherited. This omission will NOT be a problem later on. Click on Next to continue.

Pega 7 Service Accelerator (Service Wizard) - Customize Service Data

Step 4: Select Service Resources

  • Specify a ruleset and ruleset version for the auto-generated service rules. In this case, the ruleset name is Insurance and the ruleset version is 01-01-01.
  • Use the default options Configure a new service package and Configure a new service listener and click on Next to continue.

Pega 7 Service Accelerator (Service Wizard) - Select Service Resources

Step 5: Configure Data Records

  • The next screen is used to configure the new service listener. The listener needs to be configured to monitor a specified file system directory for CSV input files. In this case, the directory on the Pega (7.1.6) instance, where input files will be located is:
/usr/share/tomcat7/webapps/prweb/data
  • This folder may be different for Pega versions other than 7.1.6.
  • The Source Name Mask is *.csv and specifies that only csv files will be picked up by the File Listener for processing.

Pega 7 Service Accelerator (Service Wizard) - Configure Data Records

Step 6: Review and Save

  • Review the configuration of the Service and File Listener rules. Individual sections can be expanded by clicking on the plus (+) signs next to the labels.
  • In this example, the service type is Rule-Service-File (see Rule-Service-File at Pega Help).
  • The service package is AdjusterDataService and the final activity that will be called from the service implementation is called InsertAdjusters (…to insert a record into the data table).

Pega 7 Service Accelerator (Service Wizard) - Review and Save

  • Scroll down in the dialog to view details of the Final Activity as shown below.
  • Note that the Access Group specifies what privileges the generated Services will have.
  • The processing mode is specified as stateless, which means that each transaction (i.e. each record read from the file and inserted into the DB table) is isolated and not related to any previous one.

Pega 7 Service Accelerator (Service Wizard) - Review and Save (continued 2)

  • Since the option Configure a new service listener was selected earlier, the Service Accelerator will also generate a service listener rule. See screen shot below for details.
  • The File Listener will monitor a specified folder on the Pega host’s file system:
/usr/share/tomcat7/webapps/prweb/data
  • …and automatically read files that match the specified pattern, here: *.csv.
  • In this example, the listener is named AdjusterDataListener.
  • The boolean Disable Startup? parameter specifies whether the listener will be started automatically when PRPC is started or whether it has to be started manually through the System Management Application (SMA).

Pega 7 Service Accelerator (Service Wizard) - Review and Save (continued 3)

  • After reviewing the configuration, click on the Finish button to complete the configuration process and to run the Service Accelerator. At this point, the Service and all associated rules will be generated.

Pega 7 Service Accelerator (Service Wizard) - The service configuration process is now complete

  • A final confirmation screen, indicating the successful execution of the Service Accelerator, will be shown. Note that Pega 7.1.6 was used for this example and it seems to still use the Pega 6 UI theme for this confirmation screen.

Open the Service rule by entering its name in the search field in the Designer Studio. In this case, the name InsertAdjusters was used during configuration.

Tab: Service

  • The PRIMARY PAGE section shows the page class and the page name.
  • The PROCESSING OPTIONS section shows the execution mode. It is set to Execute synchronously, meaning that the service processes one file at a time.
  • The other execution modes allow asynchronous processing of input files (e.g.: placing files into a queue for background processing).

Pega 7 Edit Service File - Service Tab - Set Execution Mode Execute Synchronously

Tab: Method

  • This tab used to configure how PRPC detects and processes records in the input file.
  • Processing Method: is set to record at a time, which specifies that each row in an input file is parsed and then inserted into the data table immediately.
  • Record Terminator: a row in the CSV file is delimited by a carriage return and new line character, so \r\n is used here.
  • Character Encoding: UTF-8 is selected here since this is the character encoding of the input text file. During processing, PRPC converts the input characters from the specified encoding to Java String encoding (16-bit Unicode).

Pega 7 Edit Service File - Method Tab - Set Processing Method, Record Terminator and Encoding

Tab: Request

  • This tab is used to specify the Parse Segments. By default, the properties of the page class are listed here and a Final Activity is listed.
  • The final activity will be called each time a record from the input file has been parsed.
  • In this case, it will be used to insert the record into a data table.

Pega 7 Edit Service File - Request Tab - Parse Segments and Final Activity

  • Important: In this example, a Delimited ParseRule, instead of the default parse segment settings, will be used for parsing.
  • Manually remove the parse segments: Click on one of the text fields in a parse segment and then click on the X icon that appears to the far right of the segment row.
  • Also remove the entry in the Final Activity field.

Pega 7 Edit Service File - Request Tab - Remove Parse Segments

  • In the Map To auto-complete field of the empty parse segment row, select Delimited ParseRule.
  • The Map To Key text field is used to specify the name of the delimited parse rule.
  • The naming convention of the delimited parse rule is <namespace>.<file-extension> (case sensitive)
  • It will be applied for each row in the input file. The namespace has to match the last part of the page class, e.g.: ABC-Insurance-Data-Adjuster.
  • The file extension will be CSV and in this case, the Map To Key value will be Adjuster.CSV.
  • In the Activity text field, identify the activity that will be called after the current row is parsed and the data is available on the clipboard.
  • Here, the activity InsertAdjusters, which was created by the service accelerator, is called.
  • Click on the Save button to save the current settings.

Pega 7 Edit Service File - Request Tab - Map to Delimited ParseRule

  • The next step requires the configuration of the Delimited ParseRule.
  • Click on the magnifying glass icon next to the text field in the Map To Key column. This will open a new dialog window to create the rule.

Pega 7 Edit Service File - Request Tab - Open Delimited ParseRule

  • The label, identifier and record type are pre-filled based on the Map To Key value.
  • Click on Create and open to continue.

Pega 7 Designer Studio - Create Parse Delimited Rule

  • The screen shot below shows the configuration of the parse rule. Select Comma-Separated Values (CSV) for the Field Format.
  • In the Parsing Details section, create a row for each field in the input file. The order of the parsing rows has to match the order of the fields in the input file.

Pega 7 Designer Studio - Edit Parse Delimited Rule - Set Field Format to Comma-Separated Values (CSV) and Map To Clipboard

  • So, in the file below, the column ID will be mapped in the first row, the column Firstname will be mapped in the second row and so on.

Example CSV File to be Parsed

  • The description does not have to match the header values in the input file.
  • Select Clipboard in the Map To auto-complete field and then select the property in the page class rule to which the current field will be mapped.
  • Make sure the checkbox in the Required column is checked. Complete this activity for each field in the input file as shown below.
  • Note that the Lastname field from the input file is mapped to the inherited property pyLabel. This field can be used instead of creating a separate property for the last name.
  • Click on Save to save the Parse Delimited rule and then close the dialog.

Pega 7 Designer Studio - Edit Parse Delimited Rule - Parsing Details

  • It is also necessary to implement the insert activity rule that was specified earlier on the Request tab of the Service rule.
  • Again, the activity is named InsertAdjusters. The Service > Request screen is shown below again. Click on the magnifying glass to open the activity rule.
  • Note that this activity will be called for each row in the input file, i.e. it will read one row from the file and then insert one record into the data table.

Pega 7 Designer Studio - Edit Service File - Open Parse Segment Activity

  • Open the activity and navigate to the Pages & Classes tab. A page of the class for which instances will be inserted into the data table needs to be declared here.
  • In this case, instances of the class ABC-Insurance-Data-Adjuster are inserted.

Pega 7 Designer Studio - Edit Activity - Insert Activity Pages and Classes

  • Next, navigate to Steps and use the Page-New method in the first step to create a new clipboard page of this class.
  • In the second step, select the Property-Set method and enter the name of the page (Step Page) that was created in row 1.
  • Under Method Parameters, link the properties of the step page to the properties on the primary clipboard page
  • E.g.: .ID refers to the property of the step page and Primary refers to the clipboard page that will be populated by the parse delimited rule for each record in the input file.

Pega 7 Designer Studio - Edit Activity - Steps

  • In the third step, the Obj-Save method is used to save the step page, here the ABC-Insurance-Data-Adjuster, into the data table.
  • The parameter WriteNow will cause the system to immediately commit the insert operation. Make sure to save the activity rule.

The last part of the setup concerns the configuration of the File Listener rule that was created earlier, when the Service Accelerator was run. The File Listener will be configured to automatically monitor a specified directory on the PRPC file system for input files, in this case files that match the pattern .CSV.

  • If a new file is found, the File Listener will automatically invoke the Service file rule to process the input CSV file.
  • The screen shot below shows the File Listener details from the earlier Service Accelerator execution.

Pega 7 Service Accelerator (Service Wizard) - Review and Save - New Service Listener

  • Open the File Listener by searching for the listener name, in this case, the Service Accelerator created a File Listener rule called AdjusterDataListener.
  • The properties tab shows the listener properties and is pre-filled based on the selections made when the Service Accelerator was run.
  • Make sure that the Source Location directory is set properly. This is the directory, the File Listener will monitor for input files.
  • In this example, PRPC is running as a Personal Virtual Server, utilizing the VMWare Player (Pega 7.1.6 CSA Exercise System from Pega Academy).
  • A FTP client can be used to load input files to the file system of the virtual server.
  • For an example on how to setup FTP access to a Pega 7.1.6 CSA Exercise System running on VMWare, see: Example of FTP Connection to Pega 7 PRPC for Private Virtual Server Installations.
  • Click on the Test Connectivity button to confirm that the listener is configured properly and that the file source location is accessible.

Pega 7 Designer Studio - Edit File Listener - Properties Tab - Set Source Location, Source Name Mask, Service Package, Service Class and Service Method

  • A confirmation dialog as shown below should appear and display the message Connectivity test successful.

Pega 7 Designer Studio - Edit File Listener - Test Connectivity

  • If the connectivity test fails: For Private Virtual Server installations: Use the VMWare player to log into the virtual machine (architect, password or root, install) and create the input file directory and set appropriate access privileges using the commands:
sudo mkdir /usr/share/tomcat7/webapps/prweb/data
sudo chmod 777 /usr/share/tomcat7/webapps/prweb/data
  • In the below example, the data directory is now accessible by owner, group and everybody for reading and writing.

Pega 7 - File Listener - VMWare Ubuntu - Source Directory File Permissions

  • The File Listener will start monitoring the source location as soon as it is started (…when running the Service Accelerator, there is an option to specify whether the listener will start automatically when PRPC is started. In this case this option was set to false.).
  • To start the File Listener, open the System Management Application (SMA) by navigating to Designer Studio > System > Tools > System Management Application

Pega 7 Designer Studio - Opening the System Management Application

  • In the list of Nodes, click on a node name to load the configuration for that node. In this case, there is only one node called localhost.
  • If the list of nodes is empty, the Pega node under which the Service and File Listener rules were created needs to be added.
  • This can be done by clicking on the plus (+) icon in the upper left hand corner of the SMA window.
  • In order to start the File Listener, click on Listener Management in the navigation menu that appears once a node is selected.
  • Then select the listener from the Available Listeners drop-down control and click on the Start button in the section above it.
  • Once the listener is running, it will be listed in the Running Listeners section as shown below.

Pega 7 System Management Application - Listener Management

  • Note: The File Listener can be configured further: the Process tab allows to specify the polling interval, i.e. how often the listener will check the source location for new input files.
  • The Generate report file? check box can be checked to have the listener create an XML based report file (in the specified source location). The report shows details regarding input file processing such as parsing errors.
  • The File Operation parameter in the CLEANUP section can be used to specify what the listener does with input files that have been processed. In the below screen shot Delete is selected so that the listener will remove the input files from the system.

Pega 7 Edit File Listener - Process Tab - Set polling interval, generate report file and cleanup activity

  • If changes are made while the listener is running, it is required to restart the listener in order for the changes to take effect.

At this point, there are no input files in the directory the File Listener is monitoring. A FTP client such as FileZilla or the command line can be used to copy input files to the directory. In this case, PRPC is installed as a Personal Virtual Server, so the PRPC instance is running in a virtual machine with its own IP address, here 192.168.241.128.

  • By default, the virtual machine is running a FTP server and the default architect, password or root, install credentials can be used to connect to it via FTP.
  • The screen shot below shows the FileZilla configuration to connect via FTP to the virtual machine.
  • For an example on how to setup FTP access to a Pega 7.1.6 CSA Exercise System running on VMWare, see: Example of FTP Connection to Pega 7 PRPC for Private Virtual Server Installations.

FileZilla Site Manager - Configure FTP access to PRPC instance on virtual machine

  • Copy the input CSV file(s) to the source location that was specified earlier. Here it is:
/usr/share/tomcat7/webapps/prweb/data
  • The listener will pick up the file(s) and invoke the Service to parse and process it.

FileZilla File Listener Source Folder - File Listener report

  • After processing has been completed, the same directory may contain XML files (in the case of processing errors). These files can be used to debug parsing errors etc.
  • In the System Management Application, the Request Count in the Running Listeners section will show how many files the listener has processed since it was started.

System Management Application - File Listener Request Count

  • Finally, when the Data Tables view is reloaded, the Row Count for the target data table will reflect the records that were inserted.

Pega 7 Designer Studio - Data Model - Data Tables - Updated row countshowing row count

  • Clicking on the gear icon to the right of the row count will open the data table and show the inserted records.

Pega 7 Designer Studio - View Data Table Instances

Example CSV file adjusters.csv

  • Note: If the listener was configured to generate a report file (see Process tab > Generate report file?), it will be available in the same input file directory in a subfolder called report.
  • The report file will have the name of the input file with the file extension .rpt.
  • A sample report file is shown in the screen shot below. The report contains data such as the number of rows that were inserted into the data table, the exact file size in byte and the listener name that processed the input file.

Pega 7 File Listener Report File in XML Format

  • Note: If needed, an activity can also be created to purge existing data in the data table before new data from a CSV file is imported.
  • This cleanup activity can be called using the Initial Activity field in the PROCESSING PROLOG section of the Service rule as shown below.

Pega 7 Designer Studio - Edit Service File - Request Tab - Processing Prolog Initial Activity

Example of Connecting to Pega 7 PRPC PostgreSQL DB with pgAdmin

This post shows how the PRPC database –assuming PRPC is configured to use PostgreSQL– and its tables can be accessed using the pgAdmin tool. This example applies to the following PRPC installation method:

  1. PegaRULES Process Commander is installed as a Personal Virtual Server (PVS) utilizing the VMWare Player as described in the Downloading the Exercise System section of the System Architect Essentials I (7.1) and Senior System Architect (7.1) courses provided by Pega Academy.
  2. For this example, Windows 7 is used as the host operating system. The steps should be similar for other OS.

Related Posts

Summary

  1. Installation of the PostgreSQL pgAdmin Console
  2. Configuration of PostgreSQL DB Server to Accept Remote Connections
  3. Configuration of Connection Settings in postgresql.conf File
  4. Setup of PostgreSQL DB User for pgAdmin Connections
  5. Configuring the Connection to the Pega 7 DB in pgAdmin

Download the pgAdmin tool for Windows from https://www.pgadmin.org/download/windows.php or for the Mac from https://www.pgadmin.org/download/macosx.php. In this example, pgAdmin version 1.14.3 for Windows was used. Follow the pgAdmin installation instructions to install the application.

  • The exercise systems on Pega Academy use the PostgreSQL DB server as part of the PRPC personal virtual server installation.
  • Open the VMWare Player and click on the virtual machine and then click on the link Edit virtual machine settings.

VMWare Player Edit Virtual Machine Settings

  • Clicking on Network Adapter opens a view showing the current network connection settings.
  • In this example, the Network Adapter under Virtual Machine Settings of the VMWare Player is configured to use NAT (network address translation), so that the host’s IP address is shared (in this case the Windows OS on which the VMWare Player is running).
  • This will result in the virtual machine using an IP address in the 192.168 private network that is shared with the host operating system.

VMWare Player Edit Virtual Machine Settings - Network Adapter NAT Used to share the hosts IP Address

  • Next, use the VMWare Player to start the virtual machine by clicking on the link Play virtual machine and access it through the command line using the default user architect and the default password password.
  • For newer versions of the Pega Exercise System, use the default user root and the password install.

VMWare Player Ubuntu Command Line Login to Virtual Machine

  • The PostgreSQL server instance needs to be configured so that it allows connections from the 192.168 private network since pgAdmin has been installed on the host operating system.
  • Navigate to the folder /etc/postgresql/9.1/main on the virtual machine and locate the file pg_hba.conf.
  • Open the file in the vi editor using the command sudo vi pg_hba.conf

VMWare Player Ubuntu Command Line - Edit pg_hba.conf

  • In the section # IPv4 local connections, add: host all all 192.168.0.0/16 md5 to allow incoming connections from pgAdmin running on the Windows host operating system.

VMWare Player Ubuntu Command Line - Edit pg_hba.conf with VI

  • Navigate to the folder /etc/postgresql/9.1/main and locate the file postgresql.conf and open it in vi using the command:
sudo vi postgresql.conf
  • Locate the section # CONNECTIONS AND AUTHENTICATION and uncomment the parameter listen_addresses and set its value to '*'.

VMWare Player Ubuntu Command Line - Edit postgresql.conf

  • In order for the changes to take effect, the virtual machine can either be restarted or the command:
/etc/init.d/postgresql restart
  • …can be used to only restart PostgreSQL so that it applies the updated configuration files.

VMWare Player Ubuntu Command Line - Restart PostgreSql DB Server

  • The PostgreSQL DB server running on the virtual machine will now accept remote connections from any IP address.

  • It is recommended to create a dedicated PostgreSQL database user that will be used in the pgAdmin console. Execute the following command to create a new super user with access to all databases:
sudo -u postgres createuser --superuser <username>
  • Then open the PostgreSQL command line with by executing the command:
sudo -u postgres psql
  • Set the password of the new super user with the psql command:
\password <username>

VMWare Player Ubuntu Command Line - Create New PostgreSql DB User

  • The PostgreSQL server port should be 5432. It can be checked by executing the command:
sudo -u postgres psql -c "SHOW port;"

VMWare Player Ubuntu Command Line - Get PostgreSql DB Server Port 5432

  • Obtain the IP address of the virtual server by executing the command:
ifconfig -a

VMWare Player Ubuntu Command Line - Get Virtual Machine IP Address ifconfig command

  • In this case, the IP address of the virtual machine is 192.168.1.128.
  • Open the pgAdmin application on the Windows host system.

  • In pgAdmin, click on File in the top level menu and select Add Server.
  • In the New Server Registration dialog, enter the name for the connection, the host name, the port and the username and the password of the super user account created earlier.
  • Then click on Ok to open the connection.

pgAdmin Console - Add New Server - Properties

  • Double clicking on the new server connection opens a tree menu showing the Pega PRPC database named pega.
  • pgAdmin can be used to understand how PRPC operates and how it maintains data and rules by looking at the tables in the associated schemas.

pgAdmin Console - Accessing pegarules schema of pega database

Caution: Modifying or deleting data or PRPC system tables can compromise a PRPC instance and render it useless.

Examples of Circumstancing in Pega 7

Circumstancing can be used to handle special scenarios that would normally require changes to an existing rule -the base rule- without having to change that rule. Circumstancing allows a developer to create a copy of the base rule -the circumstanced rule-, which is applied at run time when a certain condition is met. This condition can be based on:

  • A single property
  • Multiple properties (multivariate)
  • A date range (time-qualified)

Summary

  1. Sample Application and Use Case
  2. Single Property Circumstancing in Pega 7
  3. Multivariate Circumstancing in Pega 7
  4. Time-Qualified Circumstancing in Pega 7

In the following examples, variants of a section rule are created to show different purchase discounts based on:

  • A customer category property: The value is either "Premium" or "Basic" (single property circumstancing).
  • 2 properties, the customer category and the state of the customer’s primary residence (multivariate circumstancing)
  • A DateTime property and a specified date range (time-qualified)

The sample application consists of a section rule that is used to collect customer information. It then uses a circumstanced section rule to display different discount information based on some elements of the provided customer data.

Pega 7 Application - Example of a Section Rule to Collect Customer Information

  • The base version of the ShowDiscount section is shown in the screen shot below. It displays a standard message to basic customers.

Pega 7 Application - Example of a Section showing a discount, this is the base rule

In this example, a circumstanced variant of the base section rule ShowDiscount is created so that a discount is shown to premium customers.

  • The circumstanced ShowDiscount rule will be shown when "Premium" is selected for the customer category in the Collect Customer Information section.
  • In the Designer Studio, the ShowDiscount section can be circumstanced by clicking on Save and then selecting Specialize by circumstance.

Pega 7 Edit Section Rule - Specialize by Circumstance

  • Select Property for the Circumstance by option.
  • This will display two fields where the Property and a Value (case-sensitive) must be entered.
  • In this example, the property is .Customer.Category of type Text and the value is "Premium".
  • Click on Create and open to create the new circumstanced rule variant and then click on Save.

Pega 7 Designer Studio - Specialize Section - Single Property

  • In this case, the specialized ShowDiscount rule will inform a premium customer of a 20% discount on all purchases.

Pega 7 Edit Section Rule -Circumstanced rule

  • At runtime, whenever "Premium" is selected for a customer category in the Collect Customer Information section…

Pega 7 Section Rule to Collect Customer Information

  • … the specialized ShowDiscount section rule is selected during rule resolution.

Pega 7 Circumstanced Section Rule showing discount at runtime

  • The base version of ShowDiscount is still selected during rule resolution whenever the category value is NOT "Premium".

Multivariate circumstancing allows the creation of a specialized rule based on multiple single-value properties.

  • For this example, another specialized rule of the ShowDiscount section is created using two single-value properties, Customer.Category and Customer.State.
  • The intention is to show a discount of 30% for a "Premium" customer that resides in the state of "California".
  • Multivariate circumstancing requires the creation of 2 additional rules: a Circumstance Template and a Circumstance Definition.

(a) Create the Circumstance Template

  • In the Designer Studio, navigate to Records > Technical and then right-click on Circumstance Template to create a new circumstance template rule.

Pega 7 Designer Studio - Create Circumstance Template Form

  • Provide a label for the circumstance Template and set the Apply to class.
  • Click on Create and open.
  • The Edit Circumstance Template dialog is used to select multiple properties that will be used by the circumstance definition.
  • In this case, the Customer.Category and Customer.State properties are added to the template.
  • Click on Save.

Pega 7 Designer Studio - Edit Circumstance Template Form

(b) Create the Circumstance Definition

  • In the Designer Studio, navigate to Records > Technical and then right-click on Circumstance Definition.
  • On the Definition tab, a decision table shows the properties from the circumstance template as columns.
  • The values in the first condition are "Premium" for Customer.Category and "California" for Customer.State.
  • This means that whenever the configured properties match the provided values, the circumstanced rule will be selected during rule resolution.

Pega 7 Designer Studio - Edit Circumstance Definition Form

(c) Multi-Variate Circumstancing for ShowDiscount

  • Open the rule that is to be circumstanced using the template and definition, here ShowDiscount.
  • Click on Save and select Specialize by circumstance.
  • Setting a Circumstance Template and a Circumstance Definition is required for the Circumstance by Template option (i.e. multivariate).

Pega 7 Designer Studio - Specialize Section - Circumstance by Template

  • Note: If the same rule has been circumstanced by a property before, the earlier circumstance rule must be deleted first.
  • A rule can not have multiple circumstance versions based on the same property (single and multivariate) as this could cause conflicts during rule resolution.
  • The newly created multivariate circumstanced section rule can be edited now. In this case, ShowDiscount will show a specific discount for premium customers from the state of California:

Pega 7 Designer Studio - Edit Circumstanced Section

  • At run time, when a given Customer instance matches the circumstance definition: Category = "Premium" AND State = "California"

Pega 7 Example Section to Collect Customer Information - Circumstance Discount Message based on State and Category

  • …the circumstanced ShowDiscount section, showing a 40% discount, will be displayed:

Multivariate specialized show discount message

Time-qualified circumstancing allows to create a variant of a rule that is based on a start date and/or an end date. At run time, the circumstanced rule is selected if the actual system time is after the start date and before the end date.

If only a start date was set, the circumstanced rule is executed if the system time at run time is after the start date. Similarly, if only an end date was specified, the circumstanced rule is executed if the system time at run time is before the end date.

  • Open the rule that is to be circumstanced by a Date range and click on Save and select the Specialize by circumstance option.
  • In the Circumstance by section select Date range only as shown below.
  • In the below example, the circumstanced rule will be selected during rule resolution when the system time is between January 6th 2016 10:00 PM and January 6th 2016 10:45 PM, i.e. the circumstanced rule will only be executed during this 45 minute window.

Pega 7 Specialize Section - Section Record Configuration - Circumstance by Date range using Start Date and End Date

  • As mentioned earlier, if only a start date is set, the circumstanced rule will be selected during rule resolution if the system time is greater than the start time.
  • In the example below, the circumstanced rule will always be executed once January 6th 2016 11:45 PM has passed.

Pega 7 Specialize Section - Section Record Configuration - Circumstance by Date range and Start Date only

  • Time-Qualified Circumstancing could be used to implement logic for displaying a special discount during the Christmas holiday season.