How to configure Service-REST in Pega?


First of all, don’t think INTEGRATION is a difficult topic in PEGA. I would say Integration is much easier than creating an activity rule 🙂

Pega makes it simple for developers. All you need to do is configure the Integration rules. Pega takes care of the rest 🙂 Pega provides useful wizards and guides the developers in creating Integration rules.

Integration is full of fun. You will be transferring data between applications. Play with your data.

Let me start from the basics. Every BPM application needs some data to process.

  • Think of any application; banking, finance, insurance; everywhere, we need some data to process.
  • Pega stores the data in the form of property rule type. Data can be stored either in the memory or can be persisted in the database.

Okay fine. Now tell me, “To process any request, is it mandatory that all the data should be available within Pega?”

No. That is not required. Data can be available in other application too.

  • If we need some data from other applications to process a request, then we can use a connector rule.
  • If some other application depends on Pega data, then we can use service rule to service their request.

What is the difference between Connector & Service?

The below picture speaks.

Imagine you have opened a Chrome web browser.  Hit Google map application.

What happens at the back-end?

  • We hit the Google maps server.
  • We are the client requesting the data.
  • The protocol used is HTTP protocol and the server sends a response.
  • The browser paints the UI with HTML and response content.

Hit the URL shown below:

You will get the raw response data. This is how the server sends the response.

HTTP protocol is used above.

What is a protocol?

  • Set of rules that ensure proper communication between applications.
  • In a web services, there are many layers.

Ex: TCP, UDP, HTTP protocols support transportation between applications.

Ex: XML, SOAP are messaging protocols.

JSON – Replacement of XML.

What is REST?

  • Representational State Transfer.
  • It uses HTTP protocol to transfer messages from server to client.
  • REST can use JSON/XML as messaging format. But maximum we use JSON.

Why JSON preferred over XML?

  • First, we need to know why we use JSON or XML.

Imagine, there are two close friends from different countries – France & Spain.

Spanish guy don’t know French as like French guy don’t understand Spanish. So how will they communicate with each other? Yes, through some common language like English.

Similarly, there may be many applications built on different languages like C, Java, Dotnet. They need some common web service messaging formats to communicate.

JSON & XML are the most commonly used messaging formats.

You can point out the differences.

  • JSON is more easy to read when compared to XML.
  • JSON supports only text and number type, whereas XML supports many data types like images etc.,. XML is basically a Mark up Language.

Why REST is preferred over SOAP?

  • REST can use JSON, XML or HTML as messaging formats to transfer data, while SOAP can use only XML.
  • REST use only URI to expose the service to outside world, where SOAP needs to expose the service interfaces.
  • As we saw before, the difference between JSON & XML, SOAP uses more bandwidth and resource for XML message formats.
  • When SOAP use HTTP as transport layer, it can use only POST method, while a REST can use all 4 HTTP methods like GET, POST, PUT, DELETE.
  • REST is quicker than SOAP.

But there are few advantages of SOAP over REST:

  1. SOAP is more secured comparing to REST. SOAP can secure the connection using WS-Security and HTTP SSL, while REST can secure only via HTTP SSL.
  2. SOAP can use HTTP, SMTP and other transport protocols, where as REST depends on HTTP protocol alone.

There is no such condition like you should always use REST over SOAP.

Think about the pros and cons, then decide 🙂

How do we configure Service-REST?

First, let’s see the requirement scenario.

External system needs to access the policy details stored in Pega system.

Let’s say the request is PolicyID and the response is in JSON format.





} }

Let’s see, how we can implement this.

 Unfortunately, Pega don’t provide us any wizard to create Service-REST.

Step 1: First you need to create Integration class structure manually.

  1. One main Integration class to hold the service rules.
  2. Other classes to support request and response messages.

In our example,

Request – PolicyID – Single value, no need to create any class structure

Response – Complex structure, we need to create a class for SampleResponse

{“SampleResponse”:                          -à Page structure




} }

Main integration class:

Specify the configuration fields in the class form.

Specify the class as concrete class and it does not belong to a class group.

Response page class: 

Now class is ready. “What will be our next step?”

Step 2: Create the request & response properties.

Request – Since request is a simple single value, we can create a single value property in main integration class.

Response – It is a complex structure.

We need to create 3 properties.

SampleResponse – A page property to hold the response.

PolicyType, PhoneNumber – Single value property in response page class.

Now class and property structure are ready 🙂

Step 3:  Create Service-REST rule.

  • It is part of Integration-Services category.

Customer package name Specify the service package name.

We will see more about service package in separate posts.

It is advisable to create the rule in Org Int class – TVSInt

There are 2 main tabs:

  1. Service tab
  2. Methods tab

Service tab
Primary Page

Page Name – You will see the default page as ‘MyServicePage’. You can keep it as such.

Page class – Specify the main integration class.

MyServicePage will contain the request properties. You can update those properties using data transform.

Resource Properties

First, let us see the paths and query strings in the URL.

This is the URL structure.

So, when you expose a new Service-REST, you can verify the URL in the service package rule.

The URL will be of this format,<ServicePackageName>/ServiceClassName/ServiceMethodName


You can add few more resource paths to the URL.

For example, if you wish that the URL should contain two more resource paths, then

Now the URL will be,


Here, policy is the resource path and PolicyID will be set dynamically based on PolicyID value.

For this testing, we leave that as blank and proceed.

Processing Options

End Requestor when done – This is applicable only for stateful sessions.

Now you can ask me.

What is stateful session?

Please go through the ‘Requestor types‘ ( post, to get the basics of how a requestor gets created for Service processing.

  • A requestor in memory will contain clipboard pages to support processing.
  • After processing a request, this requestor can end and all the pages can be cleared.
  • But, why should we populate the clipboard pages again and again for new requests which belong to same service? We can maintain the state of those clipboard pages in memory and reuse it for new requests.

This is called stateful session. If the clipboard pages are cleared after processing a request, then it can be called as ‘stateless’ session.

We can specify these values in service package rule.

  • Services will be included in Service package rule and inherits the context we specify here.
  • If we need some service to behave stateless, even though the service package is stateful, then check this checkbox.

Method is read only – Leave it unchecked always.

Execution Mode

  1. Execute synchronously – Selecting will enable the service to process the request synchronously.
  2. Execute asynchronously – Queues the request to batch processing agent, to process the request asynchronously.

We will see more of asynchronous parallel processing in a separate post.

Request Processor – Is a rule type that supports asynchronous parallel processing.

Methods tab

We know REST follows HTTP protocol and supports 4 methods:

  1. GET
  2. POST
  3. PUT

GET Method

  • Normally we use it to get some resource from server.

POST Method

  • Updates the resource in the service. It can also create.

PUT Method

  • Same as above, not able to figure out exact difference.

Follow this link to get more details:


  • Normally, we use it to delete some resource from server.

In Pega, for Service – REST, normally we use GET, POST.

The main difference between these two are:

  • In GET method, we don’t need the request body. We can send the request as query string.
  • In POST method, we will send the request in request body.
  • When the request is very simple, like our case – Only PolicyID, then we can use GET method.

Let us use GET method here.

First, we need to specify service activity.

Step 4: Create a new service activity – Handle all the processing logic in the service activity.

For now, I hard-coded the response in the MyServicePage.

Now, service activity is ready. Specify the service activity in Service-REST rule.

Now, let us specify the request parameter PolicyID in query string parameters.

By the way, we have successfully configured Service-REST 🙂

Its time to test our service. Let us test the same using PostMan application.

How do you test your Service API?

  1. You can either ping the URL or use some external testing applications like PostMan.
  2. You can run the Service rule manually by providing the request parameter.

Postman – Application used to test APIs

Step 1: Just search in Google and open the app.

Step 2: Select GET method and input the URL.

Step 3: Open the service-REST rule and do open rule trace.

Step 4: In the Postman app, click send button. You can verify the response.

Step 5: You can see the service activity run from the tracer.

We have successfully tested GET method.

Let’s try authentication.

In Step 4, you can see that we didn’t send any authorization, because we didn’t add require authentication in service package rule.

Now, check requires authentication and click send on Postman app.

Now provide the authorization parameters and click update request.

Then click send. You will receive the response.

Okay, “Shall we test the same using POST method?”

Step 1: Update the service –REST rule.

Remove the query string and send the request in request body. Use the same service activity.



Step 2: Go to Postman app and test it.

Happy paths are done.

How to handle errors in Service-REST?

There are two ways we can handle error:

  1. Service-REST response conditions.
  2. Service activity handling business exceptions.

Service-REST response conditions

Click on the plus icon to add more response conditions.

We will catch mapping error in our example.

I added a new response condition – Mapping error and set the error code to ‘001’.

If you are having more than one response conditions, then move the default condition to the last.

For a change, we can run the rule and test the exception.

Step 1: Go to actions button & click run.

Step 2: Select method as POST and don’t provide any input. Execute it.

Step 3: You will get the error code.

You can test for variety of response conditions Pega provides in the service rule.

Service activity handling business exceptions

In the service activity, you can use the business logic to capture the exception and send the error details in response page.

For Ex: Policy ID is null.

Step 1: Open the service activity.

Step 2: Introduce a step to check if policy ID is null in the pre-condition.

Step 3: If null, then set the error message in the response page and exit-activity in the transition.

Step 4: Now, run the Service REST rule with PolicyID as null.

Things to remember:

  • Decide what type of service we need to expose like creating a new work item from the request parameters or just processing the request and sending the response values etc.,.
  • Default service URL format is http://:///

You can add the resource path to this URL and can be parameterized:

  • Decide the request parameters you need to process the request. Share the same with the client. Also get the required response values, the client anticipate from our service.
  • Decide on which HTTP protocol, we need to use – GET, POST, PUT, DELETE. Maximum, we use GET or POST.
  • Create the Integration class structure, Request response properties, Service-REST rule.
  • Build your own business logic inside service activity. Set the response values in the service activity.
  • You can use JSON, XML, HTML formats as input. Preferably, use JSON to gain its advantage over XML.
  • Decide if authentication is required for our service. Authentication is recommended to secure our service.

Let me end this long post here 🙂 In my next post on Connect-REST, I will include the debugging for both services & connectors.

48 thoughts on “How to configure Service-REST in Pega?

  1. Too Good.

    There were no REST Services tutorial on the internet and now we have one.

    Expecting REST Connector tutorial as well. 🙂

    Many thanks for creating this website.

    1. Thank you so much, Aditya.
      I will post that soon.
      You are welcome.
      Please subscribe and stay tuned for more posts.

  2. Hi Prem,
    Very easy steps to learn quickly.
    Please publish Connect SOAP and Service SOAP if possible.


    1. Hi Sai,
      Thank you so much, Sai. Happy that you find these information useful 🙂
      Yeah Sai, I’ll post them as soon as I post Connect REST.
      Please stay tuned 🙂
      Premkumar G

  3. Hi Prem,

    Could you explain asynchronous service response on. I am unable to find the difference bw synchronous and asynchronous response.

  4. Hi Prem,

    At first thank you very much i learned alot about Service REST. My doubt is, If i have to configure a complex property (page or Page list) in the Request how can i do that. Can i give the complex property in the Resource Path? If yes could you please let me know.


    1. Complex property in the request, you should definitely expose it with POST method, request body data. Clients can send you the complex request using POST method. If your service needs a simple request like ‘PolicyID’, then you can use GET method and expect the users to send it via query strings.

      Resource path – you define for your service. Make it simple.
      Imagine resource path as like this C:/ProgramFiles/Pega. Will you give any complex parameters here? No right. Cool.

  5. Understood Prem. Thank you very much for the reply and now i got clear idea about Service REST. Very useful information. If possible can you please publish Listeners as well.


    1. You are welcome, Ramakrishna. Feel free to ask questions anytime. 🙂
      Okay. I’ve taken a note of it. Will post it soon. 🙂
      Please stay tuned for upcoming posts 🙂

  6. Very nice article thank you so much for this information. Keep rocking the way you are doing. Is it possible to copy this information in the MS word.

    1. Thank you so much for your encouraging words, Ravi Kishore. 🙂
      I’m so sorry to say that it is not possible to copy the content in MS Word or anything. To avoid plagiarism of the content, it has been done so.

  7. Very nice Prem Kumar
    Please share the process how to store/update the existing data in rest service using “PUT” HTTP method

    1. In Pega service, we just use those method. It is not like you can only store/update the existing data in PUT method. You have an activity and do whatever you want 🙂 But, yes theoretically PUT method is used to store/update existing data 😉

      Hope you are clear now. 🙂

  8. Prem,This posting is very helpful.Could please provide how to handle errors in integration(SOAP,REST etc…)

  9. Hi Prem,

    Firstly i would like to thank you bro, you are making life simple for people who all planning to learn. Seriously i thought it was normal blog but the way you are elaborating the concepts was deep and any one can easily understand.

    Can you post on service soap.

    A big thanks bro… 🙂

    1. Hi DS,

      You are most welcome. I’m feeling elated on reading your comments. 🙂 Thank you so much for your appreciation. 🙂
      Yeah, I’ll post about them soon. 🙂

      You are once again welcome. 🙂

  10. Hi Prem,

    Very informative and nice post, thank you.
    Can you also write a post regarding different kinds of reports available in pega,difference between them.
    And why we use RD more frequent then list and summary views?

  11. Hi Prem,

    Thank you for such an amazing, well explained and descriptive post. Now creating and understanding REST service is fun.
    Things are pretty clear to me now. You have made it really easy.
    Awaiting next post for Connectors.

    Thank you again and keep posing.

    1. Hi Garima,

      You are most welcome. Happy to hear that you find it very much useful.
      Glad to hear from you.

      Stay tuned. 🙂


    1. Thank you so much for your appreciation, Maria. 🙂 I’m feeling elated on reading your comments. Thank you so much, Maria. 🙂

  12. Hi Prem,

    Good one. Thanks a lot. I have a simple Query.
    How do we know which method(GET/POST) is picked up during runtime ?
    Is that determined by the external application ? If yes, how do we trace it from Pega end ?

    1. Yes Barathi, External application can use any method.
      I means a single Service-REST can work on work different ways based on four different methods ( GET, POST,PUT,DELETE).

      Other applications can use the method based on their requirement to invoke the service

  13. Hi Prem,

    Firstly, Thank You were much for the idea of bringing in the concept of Integration in so easy way towards us, really appreciate it.

    I was going through the Service-REST notes and tried to replicate it in the personal Edition(7.2)
    While doing it, in the 3rd Step(Create Service Rule), what should i mention in the Customer Package Name, as in the 1st or 2nd Step, it is not mentioned to create any.

    Thanks for your response.

  14. Hi Prem,

    I tried creating a service for fetching Employee Records Using the parameter ie., the query string Say Employee ID.When I tried to ping the server using postman,I have the data hard coded in the Activity and still the data is not received and shown in the Postman.Need your help in here

    1. Hi Pintu,
      You can always trace any Pega service using trace open the rule. In your service rest, other actions button trace open the rule. Now hit the service URL from postman with your request.
      Please check if the service activity is getting executed or not. If yes, check the response value.
      Please update your observation here

Leave a Reply

Your email address will not be published. Required fields are marked *