Call REST Service in Pega 7 with Connect REST Rule

This post shows how a Pega 7 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.

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

• Setup a REST Service in Pega 7.1.9 with Service REST Rule
• Creating a REST Web Service with Eclipse Neon, Tomcat 9, JAX-RS Jersey 2.24 and Jackson
• Configure Pega 7 to use HTTP Proxy for REST Services
• Example of Pega 7 SOAP Web Service Integration
• Creating a SOAP Web Service with Eclipse IDE and Tomcat

• Pega 7.1.9 (see exercise systems on Pega Academy) running on VMWare Workstation Player 12.
• Alternatively, see Running Pega 7 Exercise System on Tomcat 9 and PostgreSQL – without VMWare or VirtualBox. This setup runs faster and allows more control over the Pega 7 application.
• A sample REST service called Product Catalog was created to support this example.
• The Google Chrome application Postman was used to test the REST service in this example.

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.

• 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:

• The structure of the table is as follows:

• 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.

• 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:

• 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:

• 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.

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

• 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.

• 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.

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

• A REST client application must be able to create a JSON string for issuing a request and it must be able to parse the JSON response and then convert it into an entity in its programming language such as a Java object or a PHP array.
• 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 Rule-Connect-REST rule type 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.

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

• 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

• 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:

• Click on Next to continue.

• 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.

• 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.

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

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

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

• 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:

• 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.

• 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.

• 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.

• 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.

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

• 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:

• 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.

• 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:

• 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.

• 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.

• 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.

• 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:

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

• 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.

• 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.

• 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.

• 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.

• 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:

• Instead of Show-Page, other methods such as Apply-DataTransform would normally be used in the activity to access the GET response.
• For an example on iterating over a page list in a data transform, see: Iterating over a Page List in a Data Transform in Pega 7.

• 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:

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

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

• 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.

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

• Access the HTTP POST response. Here, it is again simply output using the Show-Page method.
• The Apply-DataTransform method would usually be used to ready the service response. See Iterating over a Page List in a Data Transform in Pega 7.

• 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.

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

• 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.

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

• 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.

• 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.

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

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

• 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.

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