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

Leave a Reply