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.