Create Pega 7 REST Service with Service REST Rule

This post shows how to create a Pega 7 REST service -using the Service REST rule- that can be consumed by external applications. In essence:

  • A Pega 7 application is the REST service provider.
  • External applications are the Pega 7 REST service consumers (or clients).
  • Pega 7.1.9 was used in this example.

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. Data Model for Pega 7 REST Service Request and Response Mappings
  4. Create New Service Package Rule for Pega 7 REST Service
  5. Create New Service REST Rule
  6. Create New Service Activity Rule
  7. Test the Pega 7 REST Service

Related Posts

1  Quick Description of Sample Application

  • 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 Pega 7 REST service is created for querying Phone records by name:

Postman - Call REST Phone Service

2  Create New Access Group and Access Role Rules

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

3  Data Model for Pega 7 REST Service Request and Response Mappings

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

4  Create New Service Package Rule for Pega 7 REST Service

  • 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.
  • Here, Requires authentication is not checked, so that any unauthenticated client can call the Pega 7 REST service.

Edit Service Package - Context Form

  • Click on Save to complete the Service Package setup.

5  Create New Service REST Rule

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

6  Create New Service Activity Rule

  • The GetPhones service activity needs to be created to query the phone records and to 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.

7  Test the Pega 7 REST Service

  • The URL for accessing the Pega 7 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 Pega 7 REST 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