Configure Pega 7 to use HTTP Proxy for REST Services

For calls to REST services, Pega 7 may have to be configured to use a HTTP proxy. This is the case when Pega 7 is run from within a network that requires Internet connections via a network proxy.

The screen shot below shows the Pega 7 Designer Studio home page. On page load, the Pega 7 will attempt to connect via a REST service to the PDN to get the news. When Pega 7 is running behind a network proxy, this call fails and the error Unable to connect to the PDN at this time. is shown.

Pega 7.1.9 - Home Page - Unable to Connect to the PDN at this Time.

  • The Pega logs show a java.net.UnknownHostException because the target host is unknown:
2017-09-20 18:08:56,601 [http-nio-8080-exec-7] [  STANDARD] [          ] [    MyStore:01.01.01] 
(nvoke.Rule_Connect_REST.Action) ERROR  [email protected] 
- com.pega.pegarules.pub.services.ConnectorException: 
Caught unhandled exception: java.net.UnknownHostException: pdn.pega.com: unknown error
  • This post shows 2 options for configuring Pega 7 to use a HTTP proxy for REST service calls.

Summary

  1. The Pega 7 pyInvokeRESTConnector Activity for REST Service Calls
  2. Option A: Set System Properties for Pega 7 HTTP Proxy in Tomcat
  3. Option B: Set System Properties for Pega 7 HTTP Proxy in Java Activity Step

Related Posts

  • The PDN News feed section relies on a data page called D_PDNFeed, which uses a Connect REST rule called pyRSSConnectService as its data source.

Pega7.1.9 Home Page - PDN News Feed Data Page D_PDNFeed

  • For Connect REST rule executions, Pega 7 uses the activity pyInvokeRESTConnector to facilitate the HTTP GET or POST call. This activity contains Java steps that use the Apache HttpPClient API.
  • In step 4 of the activity, there is logic to check for HTTP proxy system properties.

Pega 7 activity pyInvokeRESTConnector - Java step for HTTP proxy credentials

  • In order for this activity to use a HTTP proxy, these system properties need to be set:
http.proxyHost – the HTTP proxy hostname or IP address
http.proxyPort – the HTTP proxy port, ususally 80 or 8080
http.proxyUser – the username (optional)
http.proxyPassword – the password (optional)

  • System properties can be added to Tomcat using the catalina.properties file.
  • This file is located in the <tomcat-root>/conf folder.
  • On the Pega 7.1.9 Exercise System, running on a virtual machine, the file is located at:
/opt/tomcat/conf
  • On the Pega 7.1.6 Exercise System, running on a virtual machine, the file is located at:
/usr/share/tomcat7
  • Open the catalina.properties file and add the following system properties:
http.proxyHost – the HTTP proxy hostname or IP address
http.proxyPort – the HTTP proxy port, ususally 80 or 8080
http.proxyUser – the username (optional)
http.proxyPassword – the password (optional)
  • The catalina.properties file should look like this example (here, username and password are set too):

Tomcat - catalina.properties - Set System Properties

  • Note that the backslash character in the username is encoded using \u0005c as per the Unicode standard. For details on this see Java properties backslash discussion on stackoverflow.
  • Restart Tomcat or if you are running the Pega 7 Exercise System, restart the virtual machine.
  • The PDN news feed on the Designer Studio home page should now load successfully as shown below.

Pega 7.1.9 - Home Page - PDN News Feed.

  • If an activity is used to call the Connect REST rule, a Java step in the activity can be used to set the system properties before the call to the REST service.
System.setProperty("http.proxyHost", "proxy.abc.com");
System.setProperty("http.proxyPort", "8080");
System.setProperty("http.proxyUser", "users\\ssmith");
System.setProperty("http.proxyPassword", "password12345");
  • In the below example, the same Connect REST rule is executed in a custom activity using the Connect-REST method. A Java step is used to set the HTTP proxy system properties.

Activity Definition Tab - LoadPDNNewsFeed

  • When the activity is executed, the REST call succeeds and the service page contains the GET response data:

Show-Page - REST Service GET Response - PDN News Feed

Running Pega 7 Exercise System on Tomcat 9 and PostgreSQL – without VMWare or VirtualBox

The Pega Exercise System, available at Pega Academy, provides as a virtual machine disk (VMDK) file and requires a virtual machine player such as VMWare Workstation or Oracle VirtualBox to run. For details, see:

This post shows how the Pega 7 Exercise System can be installed on macOS or Windows using Tomcat 9 and the PostgreSQL DB Server – without the need for a virtual machine. Here, macOS is used but the steps for Windows are essentially the same.

Summary

  1. Download Pega 7 Application Files from Pega Exercise System Installation
  2. Export Pega 7 Database from Pega Exercise System Installation
  3. Install PostgreSQL 9 Database Server
  4. Install the PostgreSQL PL/Java Extension
  5. Import Pega 7 Database into PostgreSQL Server
  6. Install Apache Tomcat 9
  7. Configure Tomcat 9 and Deploy Pega 7 Application Files

Related Posts

  • The Pega 7 application WAR file (prweb.war) can be obtained from a Pega Exercise System installation.
  • Here, a Pega 7.1.9 Exercise System is installed and running on Oracle VM VirtualBox as explained in the Pega Academy Virtual Machine User Guide.

Pega LSA Exercise System -Running on Oracle VirtualBox

  • The Pega 7.1.9 Exercise System provides an index page at <hostname>:9080 that shows system information. The super user credentials are used for FTP access.

Pega LSA Exercise System - Welcome Page

/opt/tomcat/webapps

Pega LSA Exercise System - FTP Download Pega 7 Application Files

  • Download the 3 WAR files of the Pega 7 Exercise System distribution:
prweb.war – Rules engine and Designer Studio
prsysmgmt.war – System Management Application
prhelp.war – Online Help Pages
  • These WAR files will be used in section 7 and deployed to Tomcat 9 on the local machine.

  • Use the VM command line interface to access the Pega 7 Exercise System.
  • On Pega 7.1.9, the default credentials are username root and password install.
  • Navigate to /usr/bin and execute the pg_dump program as shown below.
pg_dump -U pega pega > pega7db.pgsql
  • The Pega 7 DB export may take a while and result in a fairly large file. Here it is 6.1 GB.

Export Pega 7 Database with pg_dump

  • Use the FileZilla FTP client again to download the Pega 7 DB file.

FTP Download Pega 7 Database from Exercise System

Install PostgreSQL Server - Download Distribution

  • Select the PostgreSQL version and the OS from the drop downs. Here, PostgreSQL 9.6.5 is used.

Install PostgreSQL Server - Select OS and PostgreSQL Version

  • Run the downloaded installer file. Here the file is named postgresql-9.6.5-1-osx.dmg.
  • Follow the installation instructions. The default settings are used in this example.

Install PostgreSQL Server - Installation - Welcome

  • The default Installation Directory is used: /Library/PostgreSQL/9.6

Install PostgreSQL Server - Select Installation Directory

  • The default Data Directory is used: /Library/PostgreSQL/9.6/data

Install PostgreSQL Server - Select Data Directory

  • Enter a password and make sure to not lose it. Here, postgres is used.

Install PostgreSQL Server - Set Password for postgres user

  • Make sure to keep the default PostgreSQL server port 5432.

Install PostgreSQL Server - Select Port 5432

  • The installation should not take more than 5 minutes.

Install PostgreSQL Server - Installation in Progress

  • After the PostgreSQL installation, download pgAdmin. Here, pgAdmin 4 v1.6 for macOS was used.

pgAdmin 4.1.6 - Download Distribution

  • Start pgAdmin. It should automatically detect the running PostgreSQL server instance.

pgAdmin - View Server Nodes and Connect to Server

  • On the left-hand side in pgAdmin, expand the Servers node, right-click on PostgreSQL 9.6, select Connect Server and enter the postgres password that was set during the installation.

pgAdmin - Connect to Server and enter Password

  • pgAdmin should now be connected to the local PostgreSQL server. The Databases node shows all databases. At this point, there will only be the default postgres DB.

pgAdmin - View Available Databases

  • The Pega 7 database depends on the PostgreSQL PL/Java extension that allows procedures, triggers and functions to be implemented in Java. PL/Java must be built from source code using Maven.
  • Pega 7 will not function without the PL/Java extension.
  • Follow the steps in this section and if needed, refer to the PL/Java git hub site for details.

4.1  Download the PL/Java Extension Source Code

  • The PL/Java source code can be dowloaded as a ZIP file from the PL/Java 1.5.0 release page or by cloning the GIT repository using the git command as shown below:
git clone https://github.com/tada/pljava.git -b REL1_5_STABLE
  • After downloading and extracting the ZIP file or after cloning the git repository, the root folder of the PL/Java Maven project should look like below.

Install PL/Java - Maven Project Structure

4.2  Download and Install Apache Maven

  • Make sure that a Java JDK is installed. Here, Java JDK 8 is used.
  • Download Apache Maven, install it and confirm that it is configured properly be executing:
mvn -version

Install PL/Java - Verify Maven Installation

4.3  Confirm that "pg_config" is Accessible

  • Maven must be able to execute pg_config located in <postgre-install-dir/bin>
  • The PostgreSQL bin folder can be added to the PATH variable as follows:
export PATH=$PATH:/Library/PostgreSQL/9.6/bin
  • Run pg_config to make sure it is accessible from the terminal. The expected output is shown below:

Install PL/Java - Verify pg_config command

4.4  Confirm that the "g++" Compiler is Accessible

  • Confirm that g++ is accessible from the terminal. The expected output is shown below:
g++ --version

Install PL/Java - Verify g++ Compiler command

4.5  Build the PL/Java Extension

  • Navigate to the root folder of the PL/Java Maven project and trigger a build by executing:
mvn clean install
  • During the build, there may be some warnings and errors related to Java types. These can be ignored.
  • A successful build looks like the screen shot below. Refer to the PL/Java Build page for details or for information on debugging unsuccessful builds.

Install PL/Java - Maven Build Success Output

4.6  Install the PostgreSQL PL/Java Extension

  • See detailed PL/Java Installation instructions on the git hub site. For macOS, from the PL/Java Maven project root folder, execute the JAR file that was created for your OS:
java -jar pljava-packaging/target/pljava-pg9.6-x86_64-MacOSX-gpp.jar
  • Make sure to run the JAR file with a user that has sufficient privileges to write to the PostgreSQL installation folder. Running the JAR file creates a postgres/pljava folder in the PostgreSQL share folder and copies other PL/Java resources to the PostgreSQL installation.

Install PL/Java - pljava folder in PostgreSQL share folder

4.7  Configure the PL/Java Extension

  • Open the PostgreSQL configuration file postgresql.conf. On macOS, the default location is:
/Library/PostgreSQL/9.6/data/postgresql.conf
  • At the bottom, under CUSTOMIZED OPTIONS, add below lines to configure the PL/Java extension.
#------------------------------------------------------------------------------
# CUSTOMIZED OPTIONS
#------------------------------------------------------------------------------

# Add settings for extensions here
pljava.libjvm_location = 
'/Library/Java/JavaVirtualMachines/jdk1.8.0_77.jdk/Contents/Home/jre/lib/jli/libjli.dylib'
pljava.classpath = '/Library/PostgreSQL/9.6/share/postgresql/pljava/pljava-1.5.1-SNAPSHOT.jar'
pljava.statement_cache_size = 10
pljava.release_lingering_savepoints = true
pljava.vmoptions = '-Xms32M -Xmx64M -XX:ParallelGCThreads=2'
pljava.debug = false
  • Restart the PostgreSQL server and open pgAdmin to continue.

4.8  Create Pega 7 Database and User

  • In pgAdmin, create the Pega 7 DB user named pega by executing the SQL command below.
CREATE USER pega WITH
  LOGIN
  SUPERUSER
  INHERIT
  NOCREATEDB
  NOCREATEROLE
  NOREPLICATION;
  • In pgAdmin, create the Pega 7 database named pega using the SQL command below.
CREATE DATABASE pega
    WITH 
    OWNER = pega
    ENCODING = 'UTF8'
    TABLESPACE = pg_default
    CONNECTION LIMIT = -1;
  • Execute the SQL commands below to configure the pega user and to set the password to pega.
ALTER ROLE pega IN DATABASE pega SET search_path TO pegadata, pegarules, public;
ALTER USER pega WITH PASSWORD 'pega';

4.9  Add the PL/Java Extension to the Pega 7 DB

  • Right-click on the pega database node and select the Query Tool.
  • Execute the below SQL command to add the extension for PL/Java to the pega database.
CREATE EXTENSION pljava;

pgAdmin - Execute CREATE EXTENSION SQL command

  • To test the extension, run the below SQL command to define a new Java-based function:
CREATE FUNCTION getsysprop(VARCHAR)
RETURNS VARCHAR
    AS 'java.lang.System.getProperty'
LANGUAGE java;

pgAdmin - Execute CREATE FUNCTION SQL command

  • Then, run the function using the syntax below:
SELECT getsysprop('java.version');
  • It should return the Java version that PL/Java is using.

pgAdmin - Execute PL/Java Function getsysprop

  • The PL/Java extension for PostgreSQL is now installed for the pega database.

  • Import the file pega7db.pgsql into the local PostgreSQL instance using the psql tool.

/Library/PostgreSQL/9.6/bin/psql -U pega pega < pega7db.pgsql
  • The Pega 7 database will be completely recreated by the import.
  • pgAdmin can be used to compare the imported DB to the one on the exercise system.

pgAdmin - View Imported Pega 7 Database

  • Navigate to the download section on the Apache Tomcat home page and select the link for your OS.
  • Here, macOS is used as the target system and the binary distribution apache-tomcat-9.0.0.M26.tar.gz is used.

Install Tomcat 9 - Download Page

  • Uncompress the downloaded file to some folder. Here, Tomcat 9 is installed at apache-tomcat-9-A.

Install Tomcat 9 - Binary Distribution Folder Structure

  • Open a new Terminal and navigate to the Tomcat 9 bin folder. Run startup.sh to start Tomcat.

Install Tomcat 9 - Start Server from macOS Terminal

  • In a browser, access http://localhost:8080 to confirm that the Tomcat 9 server is running.

Install Tomcat 9 - Welcome Page

  • By default, the Tomcat 9 context.xml file, located in <tomcat-root>/conf, contains:
<?xml version="1.0" encoding="UTF-8"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!-- The contents of this file will be loaded for each web application -->
<Context>

    <!-- Default set of monitored resources. If one of these changes, the    -->
    <!-- web application will be reloaded.                                   -->
    <WatchedResource>WEB-INF/web.xml</WatchedResource>
    <WatchedResource>WEB-INF/tomcat-web.xml</WatchedResource>
    <WatchedResource>${catalina.base}/conf/web.xml</WatchedResource>

    <!-- Uncomment this to disable session persistence across Tomcat restarts -->
    <!-- <Manager pathname="" />   -->
</Context>
  • Modify the context.xml file as shown below to add the Pega 7 DB JDBC connection parameters.
<?xml version='1.0' encoding='utf-8'?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!-- The contents of this file will be loaded for each web application -->
<Context>

<Resource name="jdbc/PegaRULES" auth="Container" type="javax.sql.DataSource" 
    driverClassName="org.postgresql.Driver" url="jdbc:postgresql://127.0.0.1:5432/pega" 
    username="pega" password="pega" initialSize="11" maxActive="100" maxIdle="30" maxWait="10000"/>

<Environment name="prconfig/database/databases/PegaRULES/defaultSchema" 
    value="pegarules" type="java.lang.String" />
<Environment name="prconfig/database/databases/PegaDATA/defaultSchema" 
    value="pegadata" type="java.lang.String" />
<Environment name="url/initialization/explicittempdir" value="path" type="java.lang.String"/>

    <!-- Default set of monitored resources -->
    <WatchedResource>WEB-INF/web.xml</WatchedResource>

    <!-- Uncomment this to disable session persistence across Tomcat restarts -->
    <Manager pathname="" />

    <!-- Uncomment this to enable Comet connection tacking (provides events
         on session expiration as well as webapp lifecycle) -->
    <!-- <Valve className="org.apache.catalina.valves.CometConnectionManagerValve" /> -->
</Context>

Tomcat 9 webapps folder with Pega 7 application WARs

  • Tomcat will automatically deploy the WAR files and start the Pega 7 application.
  • The Pega 7 Designer Studio can now be accessed at:
http://localhost:8080/prweb/PRServlet

Pega 7 Login Screen

  • The Pega 7 Online Help can now be accessed at:
http://localhost:8080/prhelp/procomhelpmain.htm#home.htm

Pega 7 Online Help

  • The Pega 7 System Management Application can now be accessed at:
http://localhost:8080/prsysmgmt/index.jsp

Pega 7 System Management Application