Service REST – its Configuration, Debugging & Error handling

Before getting into the discussion we suggest you go through the basics of integration from our earlier post.

We are super excited to write & post the article on Service REST since this being the most requested article in our queue. We did a lot of research on the complete implementation of Service REST before writing this post & hence we feel it will be more informative & useful.

Let’s first understand the HTTP methods available in Service REST.

HTTP Methods in Service REST

Pega supports the below HTTP methods in Service REST.

1. GET
2. POST
3. PUT
4. DELETE
5. PATCH

GET

• This method is used to Get/Retrieve information from the system.

POST

• This method is used to Create/Update records in the system. Pega recommends using the POST method for the Create.

PUT

• This method is used to Create/Update records in the system.
• The main difference between PUT and POST is that the PUT method is idempotent. An idempotent method means that multiple identical requests will have the same effect as a single request. This is more of a DB perspective Dead rows and Live rows.
• Pega recommends using the PUT method for Update.

DELETE

This method is used to Delete records in the system. It can also be conditionally used for the update [Update of exceptional path].

PATCH

This method Operates very similar to PUT. The PATCH method is preferred when the update is limited to 1 or 2 columns. Pega recommends using the PATCH method when the update is minimal & known.

For example, Dedicated Service REST to update Email ID of a customer record.

Service REST Architecture

From OSP, we had come up with an Architecture/Process flow diagram that depicts the execution of the Service REST.

Business Scenario

Let’s consider a Customer Management application built for OSP, a Banking organization. Pega acts as a centralized database and maintains customer information. There are multiple systems apart from Pega which customers can contact to update their information anytime.

Pega should have the capability to listen to all the updates from different systems and to maintain those details in Customer DB.

This can be easily achieved by hosting service in Pega which handles all the customer-related transactions. Once done, the external system can consume our service and start sending the customer-related updates to Pega.

Let’s quickly see the step by step implementation of Service REST with POST method to create customer record for every service invocation.

Implementation

Pega doesn’t provide any wizards to configure Service REST. Hence it should be a manual process😒.

We know it will be tough , but you will not feel the same after going through this post. We will make it very simple for you😊

Step 1: Let’s start off by creating a Service package. All our services are related to Customer transactions and it’s good to group services together under a single Service Package CRMContact.

Step 2: Once Service Package is ready,we can create Service REST rule. Service REST is available under the Integration-Services category of Records explorer.

New Rule form of Service REST accepts below parameters,

Service Name

A unique name for our service. The name of our service should convey the actual purpose of the Service. In our scenario, it can be CreateContact/ FetchContactDetails/ UpdateContact/ DeleteContact.

Service Package

This field identifies the Service Package under which this service falls. In our scenario, services will be grouped under the CRMContact service package.

Service Version

We can version our service rule based on the business need. For example, the first release of an application can point to v1 of CreateContact whereas the second release of an application can point to v2 of CreateContact.

URL Template

What is an End Point URL?😳

When we want to communicate something, we call persons by name. In the same way, When a system (Connector) wants to call another system (Service), it does that by using the Endpoint URL. Yeah, the endpoint URL will be specific to each service and the client machine uses the endpoint URL to call the service.

<<System URL>>/<<Service Package>>/<<Service Version>>/<<Service Name>>

End point URL Syntax in Pega.

What is resource parameter?😳

Endpoint URLs can’t always be static and the dynamic portion of URL is referred as resource parameters.

Now coming back to our URI template, resource parameters of an URL should be defined in this field. When URL does not have any resource parameters, then service name as such should be used in the URI template field.

Step 3: Rule form of Service REST has two main tabs Service & Methods. Let’s now see how to configure these two tabs in detail.

1) Service

Service tab in Service REST comprises of 3 sections.

• Primary Page
• Resource Properties
• Processing Options

Primary Page

Each service rule has a set of fields in the incoming requests. These incoming requests will be parsed and will be set in a clipboard page which is the primary page of the service. This section allows us to configure,

Page class

• The class context of our Primary page.
• There is no restriction in Pega to configure services only in Integration (Int-) classes. We can also have our services in Data– and Work– classes based on the business need.
• Since class OSP-Data-CustomerInfo stores customer information, this class will be the page class of our service.

Data Transform

• Data transform mentioned here will be invoked before our service activity. This can be used to map any additional fields other than the incoming request.
• In our scenario, we set a few fields using SetDefaultCustomerProps data transform.

Page name

• All the incoming requests will be parsed and will be set under the page name mentioned in this field.
• The page name mentioned here will be used as a step page for the service activity.
• Pega by default populates this as MyServicePage and this can be updated if required.
• Page mentioned here will be automatically created by the system.

Resource Properties

Most of the information in this section is related to Service URL & will be pre-populated by the system.

Service endpoint URL

• This field shows the endpoint URL of each service framed with the above-discussed syntax.
• This endpoint URL along with authentication-related information should be shared with the external system to have a successful service invocation.

URI template

• This field shows the value that we have entered in our New Rule Form for the URI template.

URL path parameters

• If the URI template has any resource parameters, then this field will show the mapping for each of those parameters.
• In the above example, Customer ID is mapped as a resource parameter. As per the configuration, the incoming resource parameter CustomerID will be mapped to property CustomerID in MyServicePage.

Processing Options

This section holds configurations that mainly controls the execution of the service rule. In most of the scenario when we configure service, this section goes unnoticed.

End Requestor When Done

• Enabling this option will ensure that the requestor created to process the request is closed after the completion of the service execution.
• This option has consideration only when processing mode is selected as Stateful in the service package. If the services are stateless, the value in this field is ignored.

Enable service SLA with fallback activity

• This option is used to achieve retry in case of timeout when a service is executed synchronously.
• Let’s discuss this in detail when we discuss error handling in service REST in the later part of the post.

Method is read-only

• Enabling this option will not count the invocation during the service call.
• Still, confused?🧐 No Worries, we’ll get into a pictorial explanation,

Enable lightweight clipboard mode

• Clipboard performance can be improved during Service execution by using the Lightweight clipboard mode option.
• The following clipboard pages/properties are not accessible when lightweight clipboard mode is selected,
  • Properties referencing a data page.
  • Linked properties.
  • Referenced properties.
  • Declarative network.
  • Limited support for declare expressions/backward and forward chaining.
  • Change tracking for property value updates in the user interface.

Execution mode

• This option is used to define the mode of execution of the service rule.

• Execute synchronously: Select this option if the service should process the request immediately.
• Execute synchronously (queue on error): Select this option if the service should queue the request for asynchronous execution only in the event of a processing failure while executing the service activity. If there is no processing error, the result is the same as a normal synchronous request.
• Execute asynchronously (queue for execution): Select this option if the service should queue the request for asynchronous execution,it returns the Queue Item ID to the external application, and ends the service call. We can see about Asynchronous execution of service in a separate post.

Service monitoring

• Pega provides an OOTB option to monitor each and every execution of the service rule when this option is enabled.
• This option can be enabled at the Service level or Service package level or DSS level service/EnableGlobalMonitoring.

2) Method

Methods tab allows us to select the appropriate HTTP method and configure request mapping, service activity, and the response mapping.

Each method in the Service REST rule when expanded has 3 sections to configure.

• Request
• Service Activity
• Response

Request

This section of the Service REST rules allows us to configure the inbound mapping of the service.

Headers

• Each service call will have few attributes mapped as the header.
• Most commonly used headers are,
  • Authorization
  • Content-Type (application/JSON, application/XML)
• Headers can also have application-specific fields. For Example, to retrieve customer information, CustomerID can be passed in the header.

Query String

• Before getting into the explanation on query string param, let’s see how Google search works for the keyword OneStopPega,

• The query string is the part of a Uniform Resource Locator  In a URL, what comes after ‘?‘ will be query string. There can be any number of query string parameter for an URL which will be separated by ‘&‘.
• Query string parameter supports the loading of the actual URL.

Message data

• This section has the actual parsing logic of the incoming request. Incoming requests can be XML or JSON and parsing logic should be selected accordingly.
• In our scenario, incoming requests will be JSON and hence the below-parsing structure is mapped.

Map to field describes the parsing logic which in our scenario is JSON.

Map to Key is the Rule-Obj-Property under which the incoming request will be set.

The property mentioned in the Map to key field can be a Page (or) Page List (or) Single value property.

• Below shown is the sample incoming request and the clipboard structure in Pega after successful parsing of the incoming request.

{
“.CustomerInfo“:{
“CustomerID“:”OSP”,
“FirstName“:”One Stop”,
“LastName“:”Pega”,
“EmailID“:”Contact@OneStopePega.com”
}
}

Service Activity

• Service activity is the place where our core business logic of the service resides.

• In our scenario, we need an activity that can map the parsed incoming request and save the details to the database as needed.

Response

This section of the Service REST rules allows us to configure the outbound mapping of the service.

Response Condition

Response condition is a kind of decision-making field where we can map responses based on different conditions.

OOTB conditions can be used to handle errors during Mapping, Security and Service execution.

Any sort of business conditions can be handled using Custom when rule created in application rule-set.

Headers

• Similar to headers in the incoming request we can also map headers to the response as well.
• Mapping for headers in response should be configured here.

Message data

• This section has the actual logic of outbound mapping. Responses can be XML or JSON and outbound logic should be selected accordingly.
• In our scenario, the response will be JSON and hence the outbound mapping looks like below,

Map from field describes the response structure. In our scenario it is JSON.

Map from Key is the Rule-Obj-Property under which the response will be set.

The property mentioned in the Map from key field can be a Page (or) Page List (or) Single value property.

• Other required response fields can also be set from the service activity.

• Below shown is the response clipboard structure in Pega & the converted JSON response.

{
“Message“:”Record Inserted Successfully”,
“StatusCode“:”200”
}

With this response mapping, we are at the end of creating and configuring our Service REST. Let’s now see how to do Error handling, testing and debugging in Service REST.

Error handling in Service REST

This is another important aspect of Service REST implementation. From the OSP dictionary, we would classify Error handling in services into three types,

• Infrastructure error.
• Business error.
• Timeout error (Fallback strategy).

Infrastructure error

Errors that are not specific to application namely service execution error, security error, mapping error will come under this category.

These kinds of infrastructure errors can be handled in the Response condition tab of the service rule.

For example, when security fails in authorization, a custom response can be set with more detailed information on the failure reason.

Business error

Errors that are specific to application namely mandatory field validation, property adherence can be handled as part of this error handling.

Business errors can be handled using service activity or by custom when rule in the response condition of service rule.

Fallback strategy

There is one more cool feature in service rule starting from Pega v7. A service SLA can be set for each service call which will get triggered if service timeouts continuously for <<n>> number of attempts.

A Service REST configured with timeout as 500 milliseconds.

If the service execution times out continuously for 3 attempts in the interval of 10 seconds each, then the activity mentioned as the fallback activity gets executed.

The fallback activity can be configured for each method in the service.

Testing Service REST

Testing a REST API should cover the below aspects

• Basic positive tests (happy path)
• Extended positive testing (All possible Positive scenarios)
• Negative testing with valid input
• Negative testing with invalid input
• Destructive testing (App possible Negative scenarios)
• Security, authorization, and permission tests (Is Required)

Any of the API clients like REST Client, PostMan can be used to test Services. We will use the PostMan application to test our CreateContact Service.

• Since we use the POST method in our service, select the POST method in PostMan and input our service endpoint URL.
• As our service is authenticated, we need to pass the required information. If this information is not valid, Service returns 400 Error code.
• The header field should denote the content-type which in our scenario is application/JSON.

• Body/PayLoad of the service that has the actual request.

• When all the configurations are done, service can be tested by clicking on the Send button. On click of send, service gets executed and the corresponding response will be shown in PostMan.

Debugging Service REST

Debugging Service REST is quite easy when compared to other rules in Pega. We can use tracer and logs to debug services.

• Open the service rule which needs to be debugged and do a trace open rule. Tracer events will show the inbound mapping, service execution and outbound mapping.

• Please make sure you enable the below setting in the tracer before tracing your service.

• You will not be allowed to trace services in the Production environment. Refer to our article on System Setting which explains how to enable service trace in the production environment.
• We can also use the Log-message method in Service activity to log our Request, Response, and other exceptions if any.

We are at the end of the post and we hope you are clear with Service REST configuration, testing, debugging and error handling in Pega.

We are glad to publish the article requested by @ Ravi, Suhas, Rajesh, Suraj on “Service REST in PEGA“.If you want us to publish any articles of your choice, please fill out this form & we will make sure that it gets published.

Stay tuned for more posts on Integration 😎