Create a REST Service in Pega 7.1.9 with Service REST Rule

This post shows how to create a REST web service in Pega 7.1.9 for consumption by external applications. In essence:

  • A Pega 7.1.9 application is the REST service provider.
  • External applications are the REST service consumers (or clients).

For examples on how to consume REST and SOAP web services from a Pega 7 application (i.e. Pega is the client), see the related posts section. For this post, the Pega 7.1.9 exercise system was used as described in: Running Pega 7 Exercise System on Tomcat 9 and PostgreSQL – without VMWare or VirtualBox.

Summary

  1. Quick Description of Sample Application
  2. Create New Access Group and Access Role Rules
  3. Create Data Model for REST Request and Response Mappings
  4. Create New Service Package Rule
  5. Create New Service REST Rule
  6. Create New Service Activity Rule
  7. Test the REST Service

Related Posts

  • In this example, an application called MyStore contains a Data Type named Phone.
  • 13 records have been created in the local data storage. The records are shown below.

Data Type - PGX-MyStore-Data-Phone

  • This post shows how a A REST service is built to query Phone records by name as shown below:

Postman - Call REST Phone Service

  • A access group and a access role rule need to be created.
  • The access group will be assigned to the Service REST rule and used for handling client requests.
  • In the Designer Studio, click on the plus icon and select Security > Access Group.

Pega 7 Designer Studio Menu - Access Group

  • Here, the access group is named MyStore:Services. Click on Create and open to continue.

Pega 7 - Create Access Group Rule

  • On the Definition tab, enter the application name and version. Here it is MyStore and 01.01.01.
  • Enter a new role name under Available roles and click on the plus icon next to it to create the role.
  • Here the role is named MyStore:ServiceClient.

Pega 7 - Edit Access Group Definition

  • When creating the Access Role, select the context and the ruleset and click on Create and open.

Pega 7 - Create Access Role

  • Add a role to provide access to the PGX-MyStore-Data-Phone data type class.
  • Here, the REST service needs to be able to read instances of that class.

Pega 7 - Edit Access Role - Set Class Privileges

  • Similarly, add access to Rule-Obj-Activity and PGX-MyStore-Int for executing activities.

Pega 7 - Access Role - View all roles

  • The service activity that will be created later, will have an applies-to class that is a subclass of PGX-MyStore-Int.

  • In order to map the incoming request data and the outgoing response data, 2 page-type properties were created in PGX-MyStore-Int-REST-Phone.
  • A single page property with a definition of PGX-MyStore-Int-REST-Phone-Request is used to map the request parameters such as ID and Name.

REST Service Request data model

  • The page list property PGX-MyStore-Int-REST-Phone-Response-Phones is used to hold the matching phone records and will be converted into the REST service response data (JSON format).

REST Service Response data model

  • The conversion from incoming JSON to the request page property and from the Pega Response.Phones page list rule to a JSON string is done automatically by the Service REST rule.

  • In the Pega 7 Designer Studio, click on the plus icon in the main header menu and select Integration-Resources > Service Package to create a new Service Package rule.

Pega 7 Designer Studio Menu - Service Package

  • Enter a description and a name for the new service package and click on Create and open.
  • Here, the Service Package Name is MyStoreRESTServices.

Pega 7 - Create Service Package

  • On the Context tab, set the processing mode to Stateless and enter the access group, MyStore:Services, that was created earlier.
  • In this example, Requires authentication is not checked, so that any unauthenticated client can call the service.

Edit Service Package - Context Form

  • Click on Save to complete the Service Package setup.

  • In the Pega 7 Designer Studio, click on the plus icon in the main header menu and select Integration-Services > Service REST to create a new Service REST rule.

Pega 7 Designer Studio Menu - Service REST

  • Enter a service name in the label field, here it is PhoneRESTService.
  • Select the service package MyStoreRESTServices in the Customer Package Name field.
  • The Customer Class Name has to be a valid Java identifier and is used to group related service methods. This name is unrelated to Rule-Obj-Class instances.
  • Click on Create and open to continue.

Pega 7 - Create New Service REST Rule

  • On the Service tab, enter the Primary page class. Here it is PGX-MyStore-Int-REST-Phone.
  • The Page name specifies the name of the service page that will be passed to service activities so they can access the -Request and -Response properties. Here, it is MyServicePage.
  • Here, the service accepts one input property that is passed as part of the URL in the Resource Path.
  • The {name} resource property is mapped to the .Request.Name property of the service page.

Edit Service REST Rule - Service Tab

  • The Execution Mode is set to Execute synchronously so that the request is handled immediately instead of being queued for later processing.
  • Switch to the Methods tab to configure the HTTP GET method as shown below.

Edit Service REST Rule - Methods Tab

  • Enter the Service Activity. Here it is GetPhones and its implementation is shown in section 6 below.
  • Leave Default for the Condition and enter application/json for the content type.
  • Under Message data, select to map from JSON and enter the page list property MyServicePage.Response.Phones, which will hold the result records.
  • The service rule will convert the page list property to a JSON array.
  • Save the Service REST rule. The method should now show up in the Service Package rule.

Service Package - Context Tab - View all Methods

  • Clicking on the endpoint URL will result in an empty JSON object at this point, since the service activity has not yet been implemented.

  • The GetPhones service activity needs to be created to query the phone records and generate the response page list.
  • The Apply to class is the same as the class of the primary page of the Service REST rule.

Pega 7 - Create New Service Activity GetPhones

  • Click on Create and open to edit the activity steps.
  • The Service Activity uses the Obj-Browse method as shown below to query phone records by name.
  • The service page MyServicePage is passed to the activity and the Request.Name property contains the {name} parameter passed in the request URL. The results are sorted in ascending order by price.

Pega 7 - Acticity Steps Tab - Obj-Browse

  • The second step uses the Property-Set method to set the Response.Phones page list of the service page using the Phones.pxResults (Code-Pega-List) populated by the Obj-Browse method.

Pega 7 - Acticity Steps Tab - Property-Set

  • The Phones and MyServicePage need to be listed on Pages and Classes as shown below.

Pega 7 - Activity Pages and Classes Tab

  • The Show-Page method can be used to test the service activity. Click on Actions > Run to execute the activity and view the PGX-MyStore-Int-REST-Phone-Response page.

Pega 7 - Run GetPhones Activity

  • The default settings on the Security tab of the service activity can be kept.

Pega 7 - GetPhones Activity Security Tab

  • Save the service activity.

  • The URL for accessing the REST service is a combination of the following elements:
http://<hostname>:<port>/prweb/PRRestService/<packageName>/<className>/<methodName>/<resourcePath>
  • The endpoint URL is also shown on the Service Package rule.

Service Package - View REST Service Endpoint URL

  • Here, the URL is:
localhost:8080/prweb/PRRestService/MyStoreRESTServices/PGX-MyStore-Phone-REST/PhoneRESTService/{name}
  • A REST service client such as Postman or a browser can be used to call the service. In the below example, the service returns all phones where the name contains Apple.

Postman - Call Pega 7 REST Service to get Apple Phones

  • Clicking on the endpoint URL on the Service Package rule form will make a call with no parameters and show all records as a JSON array in a new browser window.

Call Pega 7 REST Service from Browser

  • Use the Pega logs to debug service problems. If the service fails to return any data, make sure the Access Role is configured properly as shown in section 2.

Pega 7 Logs - Access to REST Service Activity Denied

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

How to Connect to External Microsoft SQL Server 2016 Database from Pega 7.1.9

In this example, the Pega 7.1.9 Connector and Metadata Wizard in the Designer Studio is used to create connectivity between a Pega 7 application and an external Microsoft SQL Server database table. This wizard will generate the necessary PRPC rules for mapping to the table’s columns and for browsing, inserting, updating and deleting records.

Related Posts

Summary

  1. Software and Setup used in this Example
  2. Installation of Microsoft SQL Server Developer Edition
  3. Setup of Microsoft SQL Server Management Studio
  4. Setup of Sample Database “FlightInformation
  5. Create User Account for Pega 7 JDBC Connectivity to MS SQL Server
  6. Confirm that the MS SQL Server Accepts JDBC Connections
  7. Configuration of Pega 7.1.9 prconfig.xml for MS SQL Server JDBC Support
  8. Setup of new MS SQL Server Database Instance in Pega 7.1.9
  9. Execution of Pega 7.1.9 Connector and Metadata Wizard for External DB Table
  10. Browse the External SQL Server Table with an Activity

  • Pega 7.1.9 installed as a Personal Virtual Server (PVS) running on Oracle VM VirtualBox as described in the exercise system section of the System Architect Essentials course on Pega Academy. See Pega training courses for how to register and download a Pega 7 PVS.
  • The host operating system (running Pega PVS and Microsoft SQL Server) is Windows 10 64-bit.
  • The virtual machine running Pega 7.1.9 was configured to use a Host-only Adapter and DHCP.
  • In this example, the IP address of the Pega 7 virtual machine is 192.168.56.101.
  • In this example, the IP address of the Windows 10 host OS is 192.168.56.1.

Oracle VirtualBox, Network Host-only

Microsoft SQL Server Download Website

  • It is necessary to create a Microsoft account or to login with an existing account. Once that is done, the Visual Studio Dev Essentials page will show a link to download the Microsoft SQL Server Developer Edition.
  • Visual Studio Dev Essentials can be accessed directly through this link.

Microsoft Visual Dev Studio, Tools Download

  • An installation file, called SQLServer2016-SSEI-Dev.exe, will be downloaded.
  • Execute the installation file to start the installation wizard.
  • For this example, the Basic installation type was used.

MS SQL Server Instllation, Select Basic Installation Type

  • Click on the Accept button to accept the Microsoft SQL Server 2016 License Terms.

MS SQL Server Instllation, Accept License Agreement

  • The next screen allows to specify SQL Server install location. For this example, the default location for Windows C:\Program Files\Microsoft SQL Server was used.

MS SQL Server Instllation, Select Installation Location

  • Click on the Install button to start the installation process.
  • The installer will first download the SQL Server software and then install it.

MS SQL Server Instllation, Downloading Installation Package

  • After the installation completed successfully, a confirmation screen is shown.

MS SQL Server Instllation, Installation Complete

  • Click on the Close button to exit the installation wizard.
  • A computer restart is required to complete the installation.

Microsoft SQL Server Configuration Manager, MSSQLSERVER Service is Running

  • Confirm that the MSSQLSERVER service is running. On Windows, use the SQL Server Configuration Manager.

  • The SSMS provides a graphical user interface for developing and managing SQL Server databases.
  • Download the application from the Microsoft SSMS Download page and run the file SSMS-Setup-ENU.exe and follow the installation wizard’s instructions.

Microsoft SQL Server Management Studio, Installation

  • After the installation, run the application link Microsoft SQL Server Management Studio from the Windows Start menu.

Microsoft SQL Server Management Studio, Initial Screen Connected to Local MS SQL Server Instance

  • The SSMS should automatically connect to the locally running SQL Server instance. If prompted, login with Windows user credentials.

  • A sample database and table was created for holding flight information.
  • The flight information table will be used to access its data from Pega 7.1.9.
  • In SSMS, a new database can created by right-clicking on the MS SQL Server instance and selecting Databases > New Database

Microsoft SQL Server Management Studio, New Database Menu Item

Microsoft SQL Server Management Studio, New Database Options, Partial Containment Type

  • A table can be created by right-clicking on Tables > New > Table.

Microsoft SQL Server Management Studio, Create New Table

  • In this example, a table called dbo.Flights with the following columns was created:
  • id – Auto-generated identifier (…enable Identity Specification for this column)
  • flightNumber – The flight number
  • airline – Name of the airline
  • departureTime – Departure date and time
  • arrivalTime – Arrival date and time
  • fromAirport – The origin airport name
  • toAirport – The destination airport name
  • price – The flight ticket price
  • Use the SQL CREATE TABLE command below to create the Flights table with a DDL statement.
  • Note: I used the char column type because nvarchar and nchar table column mapping did NOT work when running the Connector and Metadata Wizard in Pega 7.1.9.
CREATE TABLE [dbo].[Flights](
    [id] [numeric](18, 0) IDENTITY(1,1) NOT NULL,
    [flightNumber] [char](6) NOT NULL,
    [airline] [char](25) NOT NULL,
    [departureTime] [datetime] NOT NULL,
    [arrivalTime] [datetime] NOT NULL,
    [fromAirport] [char](25) NOT NULL,
    [toAirport] [char](25) NOT NULL,
    [price] [money] NOT NULL,
 CONSTRAINT [PK_Flights] PRIMARY KEY CLUSTERED 
(
    [id] ASC
)WITH (PAD_INDEX = OFF, 
       STATISTICS_NORECOMPUTE = OFF, 
       IGNORE_DUP_KEY = OFF, 
       ALLOW_ROW_LOCKS = ON, 
       ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
) ON [PRIMARY];

Microsoft SQL Server Management Studio, Flights Table Structure

  • 11 records were inserted into the dbo.Flights table as shown in the screen shot below.

Microsoft SQL Server Management Studio, Flights Table Data

  • The below SQL INSERT statements can be used to create the sample data.
INSERT INTO [dbo].[Flights] VALUES ('SA0078', 'Spirit Airlines', '2017-02-07 14:25:00.000', '2017-02-07 21:45:00.000', 'Fort Lauderdale (FLL)', 'Los Angeles (LAX)', 414.69);
INSERT INTO [dbo].[Flights] VALUES ('SA0079', 'Spirit Airlines', '2017-02-07 09:15:00.000', '2017-02-07 14:55:00.000', 'Fort Lauderdale (FLL)', 'Los Angeles (LAX)', 975.99);
INSERT INTO [dbo].[Flights] VALUES ('AA1122', 'American Airlines', '2017-02-10 05:35:00.000', '2017-02-10 08:40:00.000', 'Miami (MIA)', 'New Orleans (MSY)', 328.65);
INSERT INTO [dbo].[Flights] VALUES ('AA1078', 'American Airlines', '2017-02-07 09:38:00.000', '2017-02-07 18:05:00.000', 'West Palm Beach (PBA)', 'New York (JFK)', 1225.49);
INSERT INTO [dbo].[Flights] VALUES ('UA0768', 'United', '2017-03-01 10:00:00.000', '2017-03-01 12:15:00.000', 'Chicago (ORD)', 'Dallas (DFW)', 546);
INSERT INTO [dbo].[Flights] VALUES ('UA0768', 'United', '2017-03-02 10:00:00.000', '2017-03-02 12:15:00.000', 'Chicago (ORD)', 'Dallas (DFW)', 595.9);
INSERT INTO [dbo].[Flights] VALUES ('CA1718', 'Copa Airlines', '2017-02-15 07:55:00.000', '2017-02-15 09:55:00.000', 'San Francisco (SFO)', 'Fresno (FAT)', 316);
INSERT INTO [dbo].[Flights] VALUES ('AC7878', 'Air Canada', '2017-02-05 07:59:00.000', '2017-02-05 10:09:00.000', 'San Francisco (SFO)', 'Seattle (SEA)', 725.78);
INSERT INTO [dbo].[Flights] VALUES ('BA0286', 'British Airways', '2017-03-05 10:52:00.000', '2017-03-06 05:52:00.000', 'San Francisco (SFO)', 'London (LHR)', 3219.45);
INSERT INTO [dbo].[Flights] VALUES ('CH9654', 'China Airlines', '2017-03-05 07:32:00.000', '2017-03-05 07:52:00.000', 'San Francisco (SFO)', 'Shanghai (PVG)', 2199);
INSERT INTO [dbo].[Flights] VALUES ('AA3104', 'Alitalia', '2017-02-26 11:15:00.000', '2017-02-27 10:35:00.000', 'San Francisco (SFO)', 'Milan (MXP)', 4056.99);

  • It is also necessary to create a new database user account for JDBC access from Pega 7.
  • Navigate to Security > Users. Right-click to open the context menu and select New User…

Microsoft SQL Server Management Studio, Create New User Menu

  • In the Database User – New form, select "SQL user with password" for the user type.
  • Enter a user name, in this case it is pega7User and a password, here it is rules.
  • In this example, the Flights table is part of the dbo schema and it should be selected as the default one.

Microsoft SQL Server Management Studio, User Account for Pega 7 JDBC Remote Access

  • In the Database User – New form, navigate to Membership and check the option db_datareader and if needed, db_datawriter for inserting data from Pega 7.

Microsoft SQL Server Management Studio, New User Account Permissions

  • Click on OK to save the user account and close the dialog.

  • By default, the MS SQL Server Developer Edition is configured to NOT allow TCP/IP connections.
  • In order to allow remote JDBC clients to connect to the MS SQL Server instance, the SQL Configuration Manager needs to be used to change TCP/IP network settings.
  • Navigate to SQL Server Network Configuration > Protocols for MSSQLServer and enable the TCP/IP protocol as shown below.

SQL Configuration Manager, Enable TCP/IP Protocols for Remote Access

  • A simple Java program can be used to confirm that the pega7User user account and network configuration changes were done correctly and that the MS SQL Server accepts remote JDBC connections. Copy the below Java code into a file named MSSqlServerDAO.java.
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;

public class MSSqlServerDAO {
      
    public Connection getConnection(
            String host, 
            String port,
            String db,
            String user, 
            String pwd) throws SQLException {
        
        String connectionString = "jdbc:sqlserver://" + host + ":" + port 
                + ";databaseName=" + db + ";user=" + user + ";password=" + pwd;

        return DriverManager.getConnection(connectionString);
    }
   
    public static void main(String[] args) throws SQLException {
        // Establish a JDBC connection
        //
        Connection c = new MSSqlServerDAO().getConnection(
            "127.0.0.1", /* or 192.168.56.1 for Virtual Box Host-only adapter IP */
            "1433",
            "FlightInformation",
            "pega7User",
            "rules");

        // Execute a query
        //
        Statement stmt =  c.createStatement();
        ResultSet rs = stmt.executeQuery(
                "SELECT * FROM [dbo].[Flights]");
        
        // Process and print the query results
        //
        while (rs.next()) {            
            int id = rs.getInt("id");
            String flightNumber = rs.getString("flightNumber");
            String airline = rs.getString("airline");
            Float price = rs.getFloat("price");
            
            System.out.printf("%-5d %-9s %-17s   $%.2f\r\n", id, flightNumber, airline, price);
        }
    }
}
  • Download the Microsoft JDBC Driver 6.0 for SQL Server and save it to some folder.
  • Copy the Java file MSSqlServerDAO.java into the same folder.
  • From the command line, compile the program using the syntax shown below.
  • After successful compilation, the folder should contain a file named MSSqlServerDAO.class.
"<JDK_BIN_PATH>\javac" -cp <JDBC_DRIVER_FILE_PATH>\sqljdbc42.jar MSSqlServerDAO.java

Java JDBC Program for MS SQL Server Access

  • Execute the Java class file using the syntax given below. The program will connect to the specified MS SQL Server instance, execute a query and print the first 3 columns of the result set.
"<JRE_BIN_PATH>\java" -cp .;<JDBC_DRIVER_FILE_PATH>\sqljdbc42.jar MSSqlServerDAO

Run Java JDBC Program for MS SQL Server Access

  • If the program fails to connect to the MS SQL Server instance, indicating a TCP/IP communication failure, check the host system’s firewall and make appropriate changes so that TCP/IP communication on port 1443 is allowed.

  • It is necessary to copy the MS SQL Server JDBC driver file to the Pega 7.1.9 PRPC web application and to modify the PRPC prconfig.xml file so that Pega can load the JDBC driver.
  • Use the virtual machine’s command line interface (login is root / install) to get the IP address of the Pega virtual machine. Here, it is:
192.168.56.101

Oracle VirtualBox, Pega 7 Private Virtual Server Login

  • A FTP client such as FileZilla can be used to copy the sqljdbc42.jar JDBC driver file to the PRPC web application’s lib folder. In this case, i.e. Pega 7.1.9 PVS using Tomcat 7, the folder is:
/opt/tomcat/webapps/prweb/WEB-INF/lib
  • On a Pega 7.1.6 PVS exercise system, the folder is:
/usr/share/tomcat7/webapps/prweb/WEB-INF/lib
  • The default SFTP username and password for a Pega 7.1.9 Private Virtual Server (exercise system installation) is root and password.

Use FileZilla to copy sqljdbc driver to Pega 7 Private Virtual Server

  • Using an FTP client, download the prconfig.xml file and open it locally in a text editor.
  • On Pega 7.1.9, the PRPC configuration file is located under:
/opt/tomcat/webapps/prweb/WEB-INF/classes/prconfig.xml
  • On Pega 7.1.6, the PRPC configuration file is located under:
/usr/share/tomcat7/webapps/prweb/WEB-INF/classes/prconfig.xml

Use FileZilla to download Pega 7 prconfig file

  • Modify the prconfig.xml file to add an entry for the MS SQL JDBC Driver Class as shown below.
<env name="database/drivers" value="com.microsoft.sqlserver.jdbc.SQLServerDriver" />

Modify Pega 7 prconfig File for MS SQl Server JDBC Driver Support

  • Upload the prconfig.xml file back to the virtual machine.
  • Access the Tomcat 7 Manager Application through a browser, here the address is:
http://192.168.56.101:9080/manager
  • By default, the username and password is admin and admin.

Use Tomcat 7 Manager Application to Restart Pega 7 prweb Application

  • Reload the PRPC web application using the Reload button for the prweb application.

  • Open the Designer Studio, here, the URL is:
http://192.168.56.101:9080/prweb/PRServlet
  • On Pega 7.1.9 PVS exercise system, the admin login is [email protected] and install.
  • Navigate to Records > Sysadmin > Database to view all instances of external DB connections.
  • Click on the +Create button to add a new external database.

Pega 7 Designer Studio, Create New Database Instance

  • On the next screen, enter a name and description for the new external database instance.
  • Click on Create and open to proceed.

Pega 7 Designer Studio, New Database Instance Name and Description

  • On the Edit Database form select "use JDBC URL listed below" in the first drop-down.
  • In the JDBC definition text field, enter the JDBC URL. In this case, the URL is:
jdbc:sqlserver://192.168.56.1:1433;databaseName=FlightInformation
  • Enter the MS SQL Server user credentials created in section 5. Here the username is pega7User and the password is rules.

Pega 7 Designer Studio, New Database Instance Configuration

  • Test the connection by clicking on the Test Connection button on the bottom of the form.

Pega 7 Designer Studio, New Database Instance, Test Connection Success

ERROR: No Suitable Driver Found

  • Verify that the prconfig.xml file has been modified as shown in section 7 to make the JDBC driver available to PRPC.

Pega 7 Designer Studio, New Database Instance, Test Connection Failure, No Suitable Driver Found

ERROR: TCP/IP connection to the host…has failed

  • Verify that MS SQL Server is configured to accept incoming TCP/IP connections (see section 6).
  • Check MS SQL Server host OS firewall. Make sure TCP/IP connections on port 1443 are allowed.

Pega 7 Designer Studio, New Database Instance, Test Connection, TCP/IP Connection Failure

  • Here, the MS SQL Server is running on Windows 10.
  • For temporary debugging, the Windows Firewall can be turned off as shown below.

Windows 10, Disable Firewall

ERROR: TCP/IP connection to the host…has failed

  • Here, Pega 7 PVS is running on a virtual machine with an IP address of 192.168.56.101.
  • MS SQL Server may not accept connections from this IP address.
  • The SQL Server Configuration Manager can be used to allow incoming IP addresses.

SQL Server Configuration Manager, TCP/IP Settings

For more information on MS SQL Server connection troubleshooting refer to:

  • In the Pega 7 Designer Studio main menu, navigate to Integration > Connectors > Connector and Metadata Wizard >

Pega 7 Designer Studio, Select Connector and Metadata Wizard

1. Choose Purpose

  • Purpose: Generate Connector Rules
  • Metadata Type: SQL
  • Integration rule set name and version: here PGX- and 01-01-01
  • Base class for integration and data model rules: here PGX-
  • Connector Activity Class: container for browse, insert, update and delete activities

Connector and Metadata Wizard Step 1 - Choose Purpose

2a. Process Metadata – Select Database Table

  • Database Name: FlightInformation (…external MS SQL Server DB as configured in section 7)
  • Schema Name: dbo (…this schema contains the table, see section 4)
  • Table Name: Flights (…the table name in MS SQL Server)

Connector and Metadata Wizard Step 2a - Process Metadata, Select Database Table

2b. Process Metadata – Select Table Columns

  • Select the external table columns for which the wizard will generate property rules.
  • As noted earlier, using nvarchar and nchar column types in MS SQL Server caused the mapping to fail (i.e. such columns would not show up on the below form).

Connector and Metadata Wizard Step 2b - Process Metadata, Select Table Columns

2c. Process Metadata – Select SQL Operations

  • Select for which SQL operations the wizard will generate activity rules.

Connector and Metadata Wizard Step 2c - Process Metadata, Select SQL Operations

2d. Process Metadata – Select Browse Criteria

  • When "Browse the database" is selected in the previous step, this step allows to specify the columns used for querying the external table.
  • All columns were selected here using the "Select All" link.

Connector and Metadata Wizard Step 2d - Process Metadata, Select Browse Criteria

2e. Process Metadata – Map Parameter Values

  • This step shows the activities that will be created and the mapping between input parameters and external table columns.
  • The Wizard-generated activity input parameters etc. can be modified later if needed.

Connector and Metadata Wizard Step 2e - Process Metadata, Select Browse Criteria

3. Review and Save

  • The last step shows the class for the external table mapping, here it is PGX-FlightReservation-Int-Flights, and the associated property rules.
  • The Wizard-generated activities will be located in the PGX-FlightReservation-Work class.
  • Click on the Finish button to run the Wizard.

Connector and Metadata Wizard Step 3 - Review and Save

Wizard Summary

  • Once finished, all created rules and the associated rule set name- and version will be shown.
  • Here, the rule set containing the Wizard-generated rules is FlightReservationInt:01-01-01.

Connector and Metadata Wizard Step 4 - Summary

Review Generated Rules

  • The Application Explorer can be used to review and open the generated rules.
  • PGX-FlightReservation-Int contains the generated properties and a stub data transform.

Application Explorer, view generated property rules

  • Technical > Activity under PGX-FlightReservation-Work contains the generated stub activities for accessing the external table.

Application Explorer, view generated activity rules

  • The activity rules can now be used to access the external table using these Pega 7 methods:
Obj-Browse – to query the database table
Obj-Filter – to filter results of Obj-Browse
Obj-Save – to update and save a record
Obj-Delete – to delete loaded record
Obj-Delete-By-Handle – to obtain a record by ID and then delete it
Obj-Save-Cancel – to cancel the most recent uncommitted Obj-Save

  • Open the wizard-generated activity BrowseFlights and click on the Parameters tab.
  • The wizard may create unnecessary parameters, e.g. that only apply to numeric data types, where a range can be provided (e.g. to search for flights with prices between $500 and $1000).
  • Ranges for text types don’t make sense. Unnecessary parameters can be removed as needed.
  • The refactored Parameters page of the BrowseFlights activity is shown below.

Activity BrowseFlights, view parameters

  • By default, there is one entry on the Pages & Classes form. The pyTempListPage page will hold the results of Obj-Browse. Note that pyTempListPage applies to class Code-Pega-List.

Activity BrowseFlights, view Pages and Classes

  • The Steps page shows the 4 wizard-generated steps, including the invocation of Obj-Browse.
  • Step 2 uses the method Show-Page to display the Obj-Browse results as a XML page.
  • For unit testing, uncomment step 2.
  • Step 3 uses Page-Rename to use the targetPage input parameter for the results page (see When rule to check if targetPage parameter is set, if not step is skipped).

Activity BrowseFlights, view Steps and uncomment Show-Page

  • Expand the first step to view the parameters for the Obj-Browse method.
  • The MaxRecords parameter is set to 100 as a best practice. If left blank, up to 10,000 records will be returned by Obj-Browse, creating a potential performance problem.
  • The UseLightWeightList parameter is checked as a best practice, as it may reduce memory requirements during processing. See the PDN article About lightweight lists for more information.

Activity BrowseFlights, Obj-Browse method parameters

  • The Obj-Browse method has a list of query fields that will be used for selecting records. Use the check box to indicate what fields will be used to match records.
  • In the below screen shot, the selection will result in a SQL WHERE clause similar to this:
WHERE (fromAirport = param.fromAirport) AND (price >= param.fromPrice)
AND (price <= param.toPrice) ORDER BY price

Activity BrowseFlights, Browse-Obj query field selection

  • Run the BrowseFlights activity by clicking on Actions > Run in the Designer Studio.
  • A new window will open. It allow to set values for the activity’s input parameters.
  • Here, all flights from San Francisco (SFO) that cost between $500 and $3,000 are selected.

Activity BrowseFlights, Run and show input parameter page

  • Run the BrowseFlights activity by clicking on the Run button.
  • A new window will show the results of the query. In this example, 2 flights matched the query.
  • The SQL prepared statement is shown in the pxSQLStatementPost node in the pagedata XML.

Activity BrowseFlights, Show-Page XML output of query results

  • The node pxResults of type PageList contains the 2 flight records, ordered ascending by price.
  • Each item in pxResults is a single page of PGX-FlightReservation-Int-Flights.

The BrowseFlights activity can now be used in a Pega 7.1.9 application to e.g. populate a data page using its Load Activity. The other activities for inserting, updating and deleting data can be used in a similar fashion. For related examples on how to connect to external MySQL and Oracle databases, see the below posts on this blog.

Related Posts

Example of Pega 7 REST Service Integration with Connect REST Rule

This post shows how a Connect REST rule can be created using the Pega 7 Integration Wizard and how it can be used in a Pega 7 application to call an external REST service. In this example, a sample REST service called Product Catalog, implemented in PHP, and hosted on this blog, will be used for demonstration purposes.

Summary

  1. Setup Used in this Example
  2. Description of REST Web Services and the Product Catalog REST Service
  3. Setup Connect REST Rule with the Integration Wizard for HTTP GET and POST
  4. How to Use the Generated Connect REST Rules in an Activity
  5. How to Source a Data Page with the Generated Connect REST Rule

Related Posts

RESTful web services are typically called from a client application using a URL and the HTTP protocol’s GET or POST methods. REST (representational state transfer) and signifies an architectural style of application programming interfaces (API) that is characterized by lightweight components, performance, scalability and simplicity (…compared to e.g. SOAP web services). For more information on REST, see https://en.wikipedia.org/wiki/Representational_state_transfer.

Example: Product Catalog REST Service

  • The REST service in this example is called through HTTP GET and POST requests, where the payload data is formatted as a human-readable JSON string.
  • For more information on the JSON data format, see https://en.wikipedia.org/wiki/JSON.
  • A client application has to generate a valid GET or POST request, send it through HTTP using the service URL and parse the JSON response String to extract the response data.
  • These steps are done automatically in Pega 7 when using a Connect REST rule.
  • The example Product Catalog REST service that will be used in this post can be accessed through its URL from any browser or other tool that supports HTTP GET and POST:
https://www.pegaxchange.com/ProductCatalogService.php?operation=search
  • The service supports HTTP GET requests for searching the catalog and HTTP POST requests for adding products to the catalog.
  • It is backed by a MySQL database which consists of a table called productcatalog that contains 16 records as shown in the screen shot below:

MySQL Workbench showing Product Catalog DB table

  • The structure of the table is as follows:
idintegerAuto-generated primary key
namestringUnique product name, no products with the same name can exist in the DB
category – enum('Electronics', 'Books', 'Hardware')The allowed product category values
unit_price – decimalThe price of the product
description – stringA description of the product
  • As mentioned earlier, the REST service supports searching the catalog via HTTP GET requests and adding products via HTTP POST calls.
  • For both use cases, a URL query string parameter named operation must be passed.

HTTP GET Example for Searching the Catalog

  • This most basic HTTP GET request, containing the mandatory operation parameter with the value search in the URL, returns all products:
https://www.pegaxchange.com/ProductCatalogService.php?operation=search
  • The response is a JSON encoded String that contains an array of all 16 products:
{
    "status"    : "SUCCESS",
    "count"     : "16",
    "products"  : [
                       {
                           "id" : "1",
                           "name" : "Keyboard",
                           "category" : "electronics",
                           "unit_price" : "29.99",
                           "description" : "Wireless keyboard for PCs"
                       }, {
                           "id" : "2",
                           "name" : "Mouse",
                           "category" : "electronics",
                           "unit_price" : "9.95",
                           "description" : "Wireless mouse for PCs"
                       }, {
                           "id" : "3",
                           "name" : "Monitor",
                           "category" : "electronics",
                           "unit_price" : "159.49",
                           "description" : "17 inch LCD monitor "
                       }, {
                           "id" : "4",
                           "name" : "Hammer",
                           "category" : "hardware",
                           "unit_price" : "9.95",
                           "description" : "Medium sized steel hammer with wooden handle"
                       }, {
                           "id" : "5",
                           "name" : "Slot screwdriver",
                           "category" : "hardware",
                           "unit_price" : "7.95",
                           "description" : "Flat-bladed screwdriver with plastic handle"
                       }, {
                           "id" : "6",
                           "name" : "Raffles and the British Invasion of Java",
                           "category" : "books",
                           "unit_price" : "11.39",
                           "description" : "Non-fiction by Tim Hannigan"
                       }, {
                           "id" : "7",
                           "name" : "A House in Bali",
                           "category" : "books",
                           "unit_price" : "15.99",
                           "description" : "Novel by Colin McPhee and James Murdoch"
                       }, {
                           "id" : "8",
                           "name" : "One Man's Wilderness: An Alaskan Odyssey",
                           "category" : "books",
                           "unit_price" : "799.99",
                           "description" : "Travel diary by S. Keith and R. Proenneke"
                       }, {
                           "id" : "9",
                           "name" : "LCD Video Multi-media Projector",
                           "category" : "electronics",
                           "unit_price" : "1199.19",
                           "description" : "A Great Experience For Home Theater"
                       }, {
                           "id" : "10",
                           "name" : "McBook Pro",
                           "category" : "electronics",
                           "unit_price" : "1199.29",
                           "description" : "Very good computer!"
                       }, {
                           "id" : "11",
                           "name" : "Scanner",
                           "category" : "electronics",
                           "unit_price" : "19.29",
                           "description" : "Scans pictures in color"
                       }, {
                           "id" : "12",
                           "name" : "LCD TV",
                           "category" : "electronics",
                           "unit_price" : "2799.00",
                           "description" : "65 inch 4K LCD television"
                       }, {
                           "id" : "13",
                           "name" : "Travel Guide to Iceland",
                           "category" : "books",
                           "unit_price" : "12.95",
                           "description" : "Comprehensive guide to exploring Iceland"
                       }, {
                           "id" : "14",
                           "name" : "Endgame",
                           "category" : "books",
                           "unit_price" : "7.95",
                           "description" : "Biography of chess player Bobby Fisher"
                       }, {
                           "id" : "15",
                           "name" : "Chainsaw",
                           "category" : "hardware",
                           "unit_price" : "565.76",
                           "description" : "Heavy chainsaw for cutting down trees"
                       }, {
                           "id" : "16",
                           "name" : "Pliers",
                           "category" : "hardware",
                           "unit_price" : "29.99",
                           "description" : "Essential for all plumbing projects"
                       }
                  ]
}
  • The response JSON string represents an object with the following properties:
statuseither SUCCESS or ERROR, if it is ERROR, the errormsg property will be set.
countstringunique product name, no products with the same name can exist in the DB
products – enum('Electronics', 'Books', 'Hardware')the allowed product category values
errormsg – decimalthe price of the product
  • For searching the catalog based on name, category and unit_price, additional parameters must be passed in the URL.
  • For example, the below GET request searches the catalog for all products in the Electronics category, where the unit price is between $10 and $30.
https://www.pegaxchange.com/ProductCatalogService.php?operation=search&category=electronics&priceFrom=10&priceTo=30
  • The below screen shot shows the JSON response, where the request was made from Google’s Chrome browser:

Chrome HTTP GET to search via the Product Catalog REST service

HTTP POST Example for Inserting a Product

  • For issuing a HTTP POST call to the REST service, I used the Google Chrome application Postman. It can be downloaded for free and is launched as a standalone application.
  • Open Postman and create a new HTTP request. Set the method in the drop-down box to POST.
  • Enter the URL with the operation parameter set to add in the text field:
https://www.pegaxchange.com/ProductCatalogService.php?operation=add
  • No HTTP authorization is needed for calling this REST service. Leave the default value No-Auth.

Postman - Authorization - HTTP POST Request to add product to Product Catalog DB

  • One header item is required, the key is Content-Type and the value is application/json.

Postman - Headers - HTTP POST Request to add product to Product Catalog DB

  • The body of the HTTP POST message contains the actual payload.
  • In this case it is a JSON encoded String that represents a product to be inserted into the productcatalog table. Make sure to set the body payload type to raw.

Postman - Body - HTTP POST Request to add product to Product Catalog DB

  • For copy and paste use, below is the full request body payload for the opration:
{
    "product" : 
              {
                  "name" : "iPhone 7S",
                  "category" : "Electronics",
                  "unit_price" : "899.99",
                  "description" : "Newest mobile phone with 512GB of memory."
              }
}
  • When clicking on the Send button, Postman makes an HTTP POST call to the REST service.
  • The product is inserted (…given that all fields are valid and a product with the same name does not already exist) and a response is returned.
  • The response from the service shows the status of the operation as well as the auto-generated id of the product record that was inserted.

Postman - Response - HTTP POST Request to add product to Product Catalog DB

  • A HTTP GET search request with the generated id=17 now shows the newly inserted product in the response:

Postman - HTTP GET to confirm product insert

  • A REST client application must be able to create a JSON string for issuing a POST request and it must be able to parse the JSON response and then convert them into an object in its programming language such as Java or PHP.
  • There are many open source libraries that do exactly that. For Java refer to Gson provided by Google and for PHP refer to the PHP JSON library.
  • In Pega 7, the Connect REST rule encapsulates all aspects of handling HTTP requests/responses and of converting data from Pega rules to JSON Strings and vice versa.

  • To start the Integration Wizard for a new REST integration, navigate to:

DesignerStudio > Integration > Connectors > Create REST Integration.

Pega 7 Designer Studio - Integration - Connectors - Create REST Integration

  • The Integration Wizard for REST services will open in the main area of the Designer Studio and guides the developer through the integration setup.

Step 1: Enter URL

  • Enter the complete REST service URL (…query string parameters and values can be included at this point).
  • In this example, the endpoint URL for searching the Product Catalog service is:
https://www.pegaxchange.com/ProductCatalogService.php?operation=search

Pega 7 REST Integration Wizard - Step 1 - Enter URL

Step 2: Define Parameters

  • The Integration Wizard will parse the URL and if it contains query string parameters, it allows the user to configure those.
  • URL query string parameters are denoted by initial ?= characters and subsequent &= characters that separate key / value pairs. For example:
https://www.pegaxchange.com/ProductCatalogService.php?operation=search
  • …contains 1 query parameter called operation with a value of search. If the base endpoint URL does not contain query parameters, the developer can add them manually in the next step by clicking on the + icon in the Query String Parameter Name section.
  • For the Product Catalog service search, there are 5 additional query string parameters that must be added manually as shown below:

Pega 7 REST Integration Wizard - Step 2 - Define Parameters

  • Click on Next to continue.

Step 3: Select Methods

  • Check the HTTP GET and POST method checkboxes as shown below.
  • Each method needs to be either configured using sample request and response data or the Test button needs to be used to download sample data from live calls to the REST service.
  • Click on the Test button for the GET method to collect sample response data.

Pega 7 REST Integration Wizard - Step 3 - Select Methods

  • The Test Data Source dialog’s Definition tab shows the query string parameters that were configured earlier.
  • In the below screen shot, a request is made to search for all products in the Electronics category where the price is between $10 and $1,000.
  • The automatically generated HTTP GET URL for this request is shown at the top of the dialog.
  • When clicking the Test button, the service returns 4 results and shows them in a tree structure under the Tree View tab in the Response section.
  • Click on Save Data to save the response as a sample.

Pega 7 REST Integration Wizard - Test Data Source - GET Method - Request

  • The Raw tab in the Response section can be used to view the actual JSON encoded String that was sent by the REST service.

Pega 7 REST Integration Wizard - Test Data Source - GET Method - Response

  • If needed, the Details tab can be used to see HTTP response details such as the status code, here 200 and the response header:

Pega 7 REST Integration Wizard - Test Data Source - GET Method - View Response Headers

  • Close the dialog by clicking on the X icon in the upper right-hand corner to return to the main page of step 3.

Pega 7 REST Integration Wizard - Test Data Source - POST Method

  • Click on the Test button for the POST method. On the Definition tab, make sure to set the operation to add.
  • Switch to the XML/JSON tab and paste a sample POST request payload as shown below:

Pega 7 REST Integration Wizard - Test Data Source - POST Method - Request JSON Payload

  • When switching back to the Definition tab, the JSON payload should have been parsed properly and the request is now shown in a tree structure.

Pega 7 REST Integration Wizard - Test Data Source - POST Method - Request Tree Structure

  • Click on the Test button to execute the POST request for adding a new product. The service returned SUCCESS and the new id 19.
  • Again, the Tree View tab shows the response as a tree structure and the Raw and Details tabs can be used for troubleshooting.
  • Use the Save Data button to save the response as a sample.

Pega 7 REST Integration Wizard - Test Data Source - POST Method - Response

  • Close the test dialog by clicking on the X icon in the upper right hand corner and continue with step 4 of the Integration Wizard.

Step 4: Generate Records

  • The Generate Records screen allows the developer to specify names for the integration class and the Connect-REST rule. In addition, an existing or new rule set needs to be specified.
  • In order to have the Integration Wizard generate a data page, check the Generate checkbox in the Data Layer section.

Pega 7 REST Integration Wizard -Step 4- Generate Records

  • Use the Edit link in the Data Layer section to set the names of the data layer rules that will be generated:

Pega 7 REST Integration Wizard -Step 4- Generate Records - Data Layer

  • Click on Submit to return to the main screen of step 4 and click on Preview. A dialog will show what rules and how many will be created by the Integration Wizard when proceeding by clicking on the Create button:

Pega 7 REST Integration Wizard -Step 4- Generate Records - Preview

  • Finally, click on the Create button to complete the Integration Wizard and to let it generate the rules for integrating with the REST service. In this case, 41 rules were created in 14 seconds.
  • The summary page provides links to open some of the generated rules, such as the rule set, the data class and integration class.

Pega 7 REST Integration Wizard -Step 4- Generate Records - Generation Summary

  • Click on the Close button to close the Integration Wizard. The Application Explorer can be used to examine the generated rules.
  • For example, the screen shot below shows the integration class and the data model of the class that encapsulates the GET request for the Product Catalog REST service:

Pega 7 REST Integration Wizard - View Generated Rules in Application Explorer

  • The generated Connect-REST rule can be examined and changed if needed as well. It can be found in the integration class, under Integration-Connectors > Connect REST.
  • The Methods tab allows the developer to change the HTTP GET and POST method configurations.

Pega 7 REST Integration Wizard - View Generated Connect REST Rule in Application Explorer

  • The Connect REST rule can now be used in an application to make calls to the product catalog REST service.

  • In the Designer Studio, create a new activity by e.g. opening a work class and right clicking Technical > Activity > Create. Enter a name and click on Create and Open.

Designer Studio - Create SearchProductCatalog activity

  • Navigate to the Pages and Classes tab and add an entry for the class that contains the Connect REST rule. Here, that class is SAE-Int-ProductCatalog-ProductCatalog.

Designer Studio - Configure SearchProductCatalog activity - Pages and Classes

  • Switch to the Parameters tab of the activity and configure the input parameters. These will be linked to the query string parameters in the HTTP GET method:

Designer Studio - Configure SearchProductCatalog activity - Parameters

  • Switch to the Steps tab of the activity and define the steps to call the REST service as shown in the screen shot below.

Step 1: Populate the HTTP GET Request

  • Method: Property-Set
  • Here, ProductCatalog.query_GET contains the properties that will be used for the HTTP GET query string parameters. The property .query_GET.operation is hard-coded to search.
  • The other query string parameters are linked to the input parameters of the activity, e.g.: .query_GET.id is set to param.id.

Step 2: Call the REST Service

  • Method: Connect-REST
  • For the step page, enter the name of the page that was defined under Pages and Classes, here the page name is PCatalogREST.
  • The class that contains the Connect REST rule needs to be entered in the ServiceName field, here it is ProductCatalog. Set the MethodName to GET.

Step 3: Process the Service Response

  • Method: Show-Page
  • The HTTP GET response is stored in .response_GET after the service call was made.
  • The method Apply-DataTransform would normally be used to process the response.
  • For this example, the response page is only output using the method Show-Page.

Designer Studio - Configure SearchProductCatalog activity - Steps

  • Run the activity by, clicking on Actions > Run.
  • The Run Activity dialog allows to set the input parameters that will be used for the search query.
  • In the below case, the product catalog is searched for all books that cost less than $15.
  • Click on Run to execute the activity.

Designer Studio - Run SearchProductCatalog activity - Input

  • The XML output of the response_GET page will be shown in a new window.
  • It shows the raw JSON response string as well as the populated page list property called products:

Designer Studio - Run SearchProductCatalog activity - View Result

Adding a Product with HTTP POST

  • Adding a new product to the catalog, using the HTTP POST method works the same way.
  • The Pages and Classes tab remains the same as for the activity in the previous example.
  • The Parameters tab of the insert activity called AddToProductCatalog looks like this:

Designer Studio - Configure AddToProductCatalog activity - Parameters

  • For HTTP POST, the generated properties .request.query_POST, .request.body_POST and .response_POST are used.

Step 1: Populate the HTTP POST Request

  • The operation query string parameter is set to add using the Property-Set method.

Step 2: Populate the HTTP POST Body

  • The new product data elements are sent via the HTTP POST body. The property .request.body_POST is used for that and its properties are set using the activity’s input parameters: .product.name is set to .param.name and so on.

Step 3: Call the REST Service

  • Again, the method Connect-REST is used. Make sure to change the ServiceMethod to POST.

Step 4: Process the Service Response

Designer Studio - Configure AddToProductCatalog activity - Steps

  • Run the activity by, clicking on Actions > Run. The Run Activity dialog allows to set the input parameters that will be used for the insert operation.

Designer Studio - Run AddToProductCatalog activity - Input Parameters

  • Click on Run to execute the activity. The XML output of the response_POST page will be shown in a new window.

Designer Studio - Run AddToProductCatalog activity - View Result

  • The service inserted the new product and return a SUCCESS status and 22, the id of the new record.

When the Integration Wizard was run in section 4, the Generate Data Layer checkbox was checked, causing the wizard to create a data page for storing data coming from the HTTP GET method of the REST service. The data page is called D_ProductCatalog.

  • The below screen shot shows the Parameters tab of that generated data page.
  • It lists the input parameters that will be mapped to the Connect REST request data transform for setting the request parameters.

41_designerstudio_applicationexplorer_datapage_parameters

  • The Data sources section on the Definition tab shows the Connect REST rule.
  • The generated ProductCatalogRequestGET and ProductCatalogResponseGET.

40_designerstudio_applicationexplorer_datapage_definition

  • The generated ProductCatalogRequestGET data transform is shown below. It maps the data page’s input paramters to the GET query parameters of the REST service.

42_designerstudio_applicationexplorer_datapage_request_get

  • The parameters are passed into the data transform from the data page. See the Parameters link underneath the request data transform on the Definition page.
  • Clicking it opens a new dialog, where Pass current parameter page is checked.

41_1_designerstudio_applicationexplorer_datapage_parameters_passparampage

  • Likewise, the generated ProductCatalogResponseGET maps the service response to the generated data class properties.

43_designerstudio_applicationexplorer_datapage_response_get

  • The DataSource page name refers to the generated Connect REST rule.

42_designerstudio_applicationexplorer_datapage_response_get_pagesandclasses

  • The data page can be run by clicking on Actions > Run. The data page parameters can be set on the Run Data Page form. They are passed to the ProductCatalogRequestGET data transform.
  • In the below screen shot, all 17 products are returned from the catalog.

42_designerstudio_applicationexplorer_datapage_run

  • The data page can now be used in a Pega application to query the REST service.