Press "Enter" to skip to content

How to configure Connect-REST in Pega?



I am gonna start this post in a different way 😀

Why do we need friends?

  • We can trust them and share our feelings with them.
  • They help us in difficult situations.
  • They can share our works as if it is their own and there will always be some mutual understanding between friends.

This list can go endless from starting a day with friends and ending it in HIGH 😀

I just mentioned the relevant points alone. Cool 🙂

Now, let’s come to our Pega.

Why Pega needs friends (other applications)?

  1. Sharing data

Every business process revolves around data. This data can be available in other applications. Pega needs to have a friendship with them, connect with them and consume the data.

Pega can share their own data through services.

  1. Support process outside Pega

Imagine a call center application. The policy creation process is not handled within Pega. Policy creation is handled by some legacy java application. Now when the customer calls in and requests to create a policy, then Pega can connect with java application for policy creation.

Integration Connectors serve the purpose

It is highly recommended to go through ‘Service-REST‘ ( post to learn the basics of REST.

Things covered in the above post are,

  • What is REST?
  • Difference between JSON & XML.
  • Why REST is preferred over SOAP.
  • HTTP methods.

What is a Connect-REST?

  • It comes under Integration-Connectors category.
  • This rule helps in implementing connections with other applications using REST.

How do we configure Connect-REST?

Before configuring a Connect-REST rule, there are some prerequisites to collect from the service provider.

  1. The Service URL
  2. Request & response parameters
  3. HTTP method they host the service
  4. Authentication, if any

In the previous post on Service-REST, we created a new Service API right?!

We are going to use the same service API as service provider

FetchPolicyDetails API specifications

URL – http:// <HostName>/prweb/PRRestService/TestServicePackage/FetchPolicyDetails/FetchPolicyDetails

Request – PolicyID

Response –

{ “SampleResponse”:





All the three basic information are handy. Let’s straightly jump to configuring Connect-REST.

Pega provides a wizard to create REST Integration.

Guys, really it is a very simple wizard 🙂

Let me walk you through the wizard.

Designer studio -> Integration -> Connectors -> Create REST Integration

This is basically a 4 step screen flow.

Connection – Specify all the connections details.

System details

Name Enter the name of the system, which we are going to connect to consume the service.

Endpoint URL Enter the complete URL of the service.

  • If you enter the complete URL path, then resource path will be pre-populated.
  • You can see how the path is identified. Words separated by ‘/’ in the URL.
  • You also have an option to make the resource path as parameter.

Why do we parameterize resource?

Say for example, I host a service based on geographical location. I provide one type of service for India and another for USA.

The URL can be  –{INDIA} or{USA}. We can parameterize the country name in resource path.

Query String parameters

For GET & Delete HTTP methods, we can specify the query strings.

First, let’s test GET method.

So we can specify the request as query string  – PolicyID


If the service expects any header values, then we can provide those in header. Else, leave it blank.


  • This makes use of Authentication Profile data instance.
  • You can either create or use existing authentication profile data instance.

I will just touch the basics with respect to wizard. We will see more details in Authentication posts.

Authentication scheme –

a. Basic – Provides the user identifier & password values.

Here the service provider implemented basic authentication. We need to send the matching username & password to authenticate.

b. NTLM – Network LAN Manager – Microsoft security protocol.

c. OAuth – This is an interesting method of authentication. It avoids the basic authentication like providing username & password.

OAuth example – I think you might have come across this in many android applications.

Some applications provide a facility to sign in using Google or facebook. The underlying authentication mode is OAuth. We will see about this very soon 🙂

Since we are going to consume our own Service-REST, we will use basic authentication here.

  • Service is also hosted in Pega. So provide any valid User name & Password.
  • Remember in Pega service, authentication happens using service package data instance.
  • Host, realm, preemptive authentication; leave it blank. We will see it authentication profile topic.

We have completed filling the configuration in connection node.

Resource methods

  • Select the method on which the service is hosted. Here in the example, we have used GET method.
  • You have an option to override the query string and header fields in this screen.

Complete it and move to the third screen.

Data Model

Here, you can specify the configuration for request & response parameters.

Sample We can use the sample request & response to create the Integration data model.

Integration data model  –  Integration classes,  request &  response property structure.

We have two options.

1. Add a REST response – Use this when your service is ready.

Click on the ‘Add a REST response‘.

After providing the request, click Run. You will get the sample response.

Click on Submit. You have taken a sample response now.

2. Add a file – Use this when your service is not ready & when you have the sample in file.

You can upload the sample request and response files.

Click on Add a file link.

You will have an option to choose a file. You can either choose JSON/XML .

  • If you have notepad ++, then you can easily create a json file.
  • You can also create the JSON file online. You can use the link,

  • Provide the response sample and save the file to your disk.

  • You can then upload the json file.

Now, we have provided the sample response to Pega.


Integration layer

  • Here you can specify the Integration class name, connect-REST name, ruleset name.
  • You can update all 3 with the edit icon.

Data Layer

  • You can specify the data type, data page name and ruleset.
  • You can also update those using edit icon.

You can also preview the record count.

Click on Create to complete the wizard.

We have created 22 records.

What are the rules get created?

FetchPolicyDetailsAPI  – Main Integration Class

Expand the class.

It contains,

  1. Connect – REST rule– FetchPolicyDetails
  2. Request page              – request
  3. Response page           – response_GET
  4. Data transform          – Sets the request value

Request –

Expand the request property.

  • TestServicePackage property is created because we made it as a parameter in resource path.

Request -> query_GET -> PolicyID

You may get a question now. Why there is an extra layer out here? We can set PolicyID directly in request page. So, why is there query_GET page?”

Let me remind you the wizard screen.

  • A single Connect-REST rule can support all four methods. You can select all methods, with different request & response.
  • When you call from activity, you can choose which method to invoke.

This is why Pega created a middle layer query_GET 🙂 It can be extended to query_POST/PUT/DELETE.

Response –

Each request will have a different response. So Pega creates a response page for GET.

Request, Response Class structure

Obviously, all the page properties will contain different classes.

  1. request
  2. query_GET
  3. response_GET
  4. SampleResponse

For all the 4 page property, pega creates 4 new classes.

Now request, response and class structure are ready.

Data Transform

See how Pega created the rules for us 🙂

What are the configuration points in Connect-REST rule?

There are two main tabs.

1. Service tab

Resource properties

Resource path You can see the resource path value ‘TestServicePackage’  is passed dynamically.

Authentication A new authentication profile is created. You can open the data instance and check the basic credentials we provided at the wizard time.

Secure protocol configuration – You can specify the SSL/TLS version – Use default.

Security settings

Truststore Stores the public SSL certificates of the server to connect.

Keystore Stores the private keys to connect with Servers.

Really this is a vast topic. I will concentrate it on some other posts 🙂


Response timeout Remember this is in milliseconds. Once the timeout seconds get crossed, the connection fails with an error message.

Maintain session  Remember stateful sessions.

  • If the service provider maintains stateful sessions, then we can check this checkbox and specify a connection ID say ‘Conn-1’.
  • You can use the same connection ID in other connectors to share the same session data.

Error handling, processing options – Same as service-REST.

Methods tab

Exactly same as Service-REST 🙂

Request –

Response –

Wizard also creates all the required properties.

We have analyzed all the properties created by the wizard.

How to configure a Connect-REST manually?

We will try connecting with the same service we used in wizard.

Whenever you start manual creation, go with class creation first.

Step 1: Create the class structure.

We are not going to reuse all the 4 methods. We will create only for POST method.

Create a new main integration class.

Request – PolicyID – Since it is a single field, there is no need to create a class.

Response Create a new class for response.

Step 2: Create a request & response parameters/properties.

Request Creates a single value property. PolicyID

Response – Creates 3 properties.

a) Sample response

b) PolicyType Single value property.

c) PhoneNumber  Single value property.

Step 3: Create a Connect-REST rule.

Service tab

Resource path Provides the URL.

Resource  parameters We will keep it blank.

Authentication We will use the same authentication, we created in wizard 🙂

Leave the remaining fields as such.

Methods tab

In the POST method, map the request body from clipboard – .PolicyID


Things to remember while configuring REST integration:

  • Before creating a Connect-REST, check the following from the service provider.
  1. End point URL
  2. Request, response parameter
  3. HTTP method
  4. Authentication if any
  • As a best practice you use wizard to create REST integration. Within minutes, you can configure the REST Integration 🙂
  • If the service provider use SSL certificates, the get those and import those in truststore.

How to write a connector activity?

There are 4 steps involved in connector activity.

Create a new connector activity

Step 1: Create a new page.

Step 2: Set the request parameters.

  • For simple request, you can directly use property-set to set in the request page.
  • For complex request, you can use a Data transform. Rarely, if you use xml, then you can use xml stream in Property-set-xml.

Step 3: Use a Connect-REST method to invoke the connector.

Method name You can specify any method GET/POST/PUT/DELETE.

Execution mode

a) Run – Synchronous execution; in the same requestor.

Current processing depends on the response.

b) Run in parallel – Asynchronous execution; in the child requestor. You can use connect-wait method to later on in the activity to get results from the connector.

Current process depends on the response in later stage.

c) Queue – You can specify a connect process requestor data instance to queue the request. ProcessConnectQueue agent process the request in background.

Current process is independent of the response.

Step 4: You can use a data transform to set the response to required properties. You can also use some parse rules to parse the complex response.

For testing purpose, use a show-page method as a last step.

  • Service activity is ready. Let’s test by invoking the service.
  • Go to actions button & run the service.

  • You can see that the sample response page contains the response values.
  • You can also see that the pyStatusMessage, pyStatusValue return GOOD.

We have successfully created a REST integration.

How Pega handles everything at the backend?

Just use tracer and run the connector activity.

  • You will see, once the Connect-REST method begins, Pega Engine invokes an activity ‘Invoke’ in class Rule-Connect-REST.
  • Say it SOAP, FILE or any connectors Pega calls ‘Invoke’ activity in the respective class.

Just search a rule Invoke.

You can see the rule available in almost all the connector classes.

Let’s check, what this activity does.

The activity is full of java steps 🙁

You can see in the 5th step, it validates the request data we configured in the Connect-REST rule.

Let us modify the request in Connect-REST rule to some error criteria.

I changed it from clipboard to JSON.

Now try running the activity again.

  • It is full of errors starting from 5th step.

The error is ‘GetPolicyDetails.PolicyID was of mode String while was expecting Page mode’.

Rememeber, whenever you use JSON mapping, specify a page mode property & set the request value in that page 🙂

In the 7th step, it calls the processing activity.

Processing activity name is set in 4th step.

This is the main activity ‘pyRESTInvokeConnector’.

  • This is full of java code. You can see the step description and know what is happening in each step.
  • 6th step executes the HTTP method and response, error all set in Invoke activity.

How to handle error in Connect-REST?

1. Connect-Method transition

Note: You need to specify both, when if true & on exception to capture all the error conditions.

This is without error handling in transition step. All activities end abruptly throwing exception.

When you use transition, the activity step jumps to the exception handling step and the process resumes.

2. Error handling in data pages

We know connectors can be used in data pages as source.

You can use an activity here to capture the exception in the data page and do any required action.

3. Connection Flow problem

  • This is not applicable when transition is not handled in connector activity or when connector is invoked from Data page.

We specify the connection flow problem in the Connect-REST service tab – ConnectionProblem

Connection Problem

  • You can see when resource is unavailable, it goes to IncompleteConnections workbasket and retries connection using an SLA – Retry connection.
  • If the exception is other than IncompleteConnections, then the spin off sub process is invoked.


It goes to ProblemFlow workbasket.

Based on the business requirement, you can use your own customized flow in the Error handling section – Error handler flow.

How to debug Connect-REST?

1. Use Log-message method to log the Connection – Errors. In connect-REST transition, you can jump to Log-Message method.

Now run the activity, by providing invalid request.

Go to Designer Studio -> System -> Operations -> Logs -> Logfiles -> Pega Logs

You can see the error message captured in log file.

Logging level We set the logging level based on the environment.

2. Tracer – Since connectors run in the requestor session, run the tracer and capture the exceptions.

3. Use Loggers – This is an interesting topic.

  • You need to log all the steps involved in REST integration. You can use loggers to print those in log files.
  • This is the logger class for Connect-REST.


Go to Designer Studio -> System -> Operations -> Logs -> Log level settings

Change the current level to ‘Debug‘.

Now run the activity and invoke the Connect-REST.

  • You can see how each step in pyInvokeRESTConnector activity returns response.
  • You can download the log file and see the complete input output request parameters and all processing.

Really, I need REST 🙂 Guys if you need any additional info or some clarifications, then please feel free to drop comments below.

  1. Sai Sai

    Hi Prem,

    Very much informative blog.
    Thank You so much for this much…of support.
    Please post Connect SOAP and Service SOAP.

    • Premkumar G Premkumar G

      Hi Sai,

      Thank you so much for your appreciation. Happy to hear!! 😀
      Yeah, Sai. I’ll post them soon. 🙂
      Please subscribe and stay tuned for upcoming posts. 🙂

      • dheeraj dheeraj

        can explain in detail how to connect the payment gateway through
        pega .

  2. Bhargav Bhargav

    Hi Prem ,

    Great Stuff ….. amazing post related to integration module.

    • Premkumar G Premkumar G

      Thank you so much for your appreciation, Bhargav. 🙂
      Happy to hear. 😀

  3. Bhanu Reddy Bhanu Reddy

    Hey Prem,

    I have one question connect-rest with queue mode.. my requirement is I don’t need response immediately and need it after 30 min 0r 1hr..for that I wanted to use queue mode..queue mode is working fine storing only success in queue table….

    I want to map repose back to case after 30 min or 1 hr…

    Do you have any idea how map response back from queue mode ??

    • Premkumar G Premkumar G

      Yes Bhanu. You can achieve that. You need to specify a Connect Request processor and queue the record to a new queue table. You can have an agent to process those queue items. The agent activity can open the case and set the response. This is really a big requirement. I need some screenshots to explain completely. Wait for few days, a separate post on parallel processing is on the way. 🙂

  4. VUKA Srikanth VUKA Srikanth

    Hi Sai the blog is too good …. thank for posting information in deatil please can you post information about case type

    • Premkumar G Premkumar G

      Thank you so much for your appreciation. Feeling happy to hear 🙂
      Yeah, I’ve noted it down. Will post it soon.
      Please subscribe and stay tuned for upcoming posts.

  5. sai sai

    Hi Prem,

    who Provides that WSDL url ..?

    • Premkumar G Premkumar G

      For connect-REST, you dont need any WSDL URL.

      The service providers should provide the WSDL URL.

    • sai sai

      For Connect_SOAP ?

      • Premkumar G Premkumar G

        Obviously for connect – Soap we need the WSDL details from service providers 🙂

  6. Jessy Jessy

    How to configure endpoint URL dynamically

    • Premkumar G Premkumar G

      Hi Jessy,
      Yes. You can configure the endpoint dynamically. You can make use of dynamic referencing functionality. Pre-load the URL in a property before calling the connect-REST method & refer the property in connect rule.

      The best way is to load a node level data page to hold all the environmental settings details like other system URL. This data page can be reused by all requestors connected to the node. You can refer the property in the datapage dynamically in the URL field.

  7. Amartya Amartya

    Really nice to get Pega’s hot topics at one place in such a well explained manner.
    Can you please post some tutorials for MQ, JMS and Listeners(Email,FIle etc).
    Thanks in Advance.. 🙂

    • Premkumar G Premkumar G

      Thank you so much for you appreciation, Amartya 🙂
      Yeah, I’ve noted those down. I’ll post them soon.
      You are welcome and stay tuned for new posts. 🙂

  8. Kumar Kumar

    Hi prem,

    We have a requirement like..when we connect to some external system from Pega, and if for some reason the connect soap fails, we are not supposed to handle the exception immediately.We need to retry for 5 or 6 times and if still the connection soap fails, we need to do exception handling and populate error to user. How do we do this retry Job?


    • Premkumar G Premkumar G

      Hi Kumar,

      You need to try and make use of Pega OOTB exception handling functionality using ConnectionProblem flow.
      The existing connection problem flow, tries for 5 times only when the exception is ‘Resource – unavailable’
      Please go through the flow and specialize it in your class & use it 🙂

  9. Pega learner Pega learner

    Hi prem,
    Very informative post..
    Please provide the advantages of using connect-REST over connect-soap. Also please post a tutorial on Data pages and all its concepts like load management, scope n dynamic loading of data pages….

    Thanks once again for the very useful post…

      • ishita das ishita das

        Very good posts. But off late noticed the content got modified. There was a section about advantage of soap over rest and also there was a seperate post about authetication both part is missing. The old post was better. Please look in to it.

  10. Sudipta Biswas Sudipta Biswas

    Hi Prem,
    Really a nice post! Can you please elaborate more on “Truststore” and “Keystore”?

    • Premkumar G Premkumar G

      Thanks Sudipta 🙂 I will make a post on truststore and keystore soon 🙂

  11. Pradeep Pradeep

    Hi Prem,

    I have one confusion between Run , Run in parallel and Queue

    my understanding is

    RUN; it will execute until response is received , that means it will not execute the next step in that activity until response receive

    Run In parallel : is Synchronous process

    Queue : Asynhronous Process

    Can you correct me here if am wrong


    • Premkumar G Premkumar G

      Hi Pradeep,

      You are confused with Run in parallel and Queue.
      Actually both refers to asynchronous processing ( parallel). It means the current requestor will not wait for the response.

      But here in our Connector rules, there are some difference in Run in parallel and Queue.
      Run in parallel – we just make the request in a child requestor. Here we no need to wait for the synchronous response. If you need the response in later stage of the activity, you can use Connect-Wait method to wait for the response.
      Queue – In this case we queue the request for background processing – Connect Request processor and agents are involved.

      I planned a topic on asynchronous processing :). Hope I will get it soon

  12. Pradeep Pradeep

    Hi Prem,

    Thank you so much for your response

    • Premkumar G Premkumar G

      Hi Pradeep,

      I’m so much sorry for replying very late. I’m little busy with my project, since the deadline is very near. I will explain well and clear all of your technical doubts soon. Please bear with me for a few days, I’ll definitely help you clear your doubts.

  13. Suman Suman

    nice article. Everything explained very clearly. Thanks for your patience.

    • Premkumar G Premkumar G

      Happy to hear that you like it, Suman. 🙂
      You are most welcome 🙂

  14. Manikanta Manikanta

    Hi Prem

    It’s very informative and valuable.
    Could you please post some tutorials on ReportDefinition, when should we use joins in ReportDefinition and about necessity of exposing the properties

  15. Pradeep Pradeep

    Hi Prem,

    Can you please help me on. How to parse JSON response.
    Do we have any parsing rule.?


    • Premkumar G Premkumar G

      Hi Pradeep,
      JSON formats are exact replica of out pega data model – Name value pairs.
      You don’t need to parse JSOn explicitly. Everything handled within the system 🙂

  16. DS DS

    Hi Prem,

    Is there any way to compress Rest Request and decompress rest response.
    If yes can you please let me know.

    • Premkumar G Premkumar G

      Hi DS,
      Can you please provide some more details. compress the request?!. In which scenarion you will be using that

    • DS DS

      Hi Prem,

      There is no particular scenario to compress the request size we are checking whether Connect-Rest will have that feasibility or not like service rest.

  17. incredibleallen incredibleallen


    Do you have any information or resources on making a Connect-Rest call to MuleSoft.

  18. Pradeep Pradeep

    Hi Prem,

    When i run Connect-REST method in activity, finding issue in mapping.
    Status Message: Attempting to map data to property .PropertyName with unsupported mode: Unknown

    can please help me, how can i resolve this

  19. saumya saumya

    Thank you for the post.Really very informative.I followed the post.However I am getting 304 server error while running connect-Rest.Can you throw some inputs.

    Error Message:The server sent a status code of 304 ,indicating that nothing has changed since the last request.

  20. viswas viswas


    When i call my Connect-Rest i am getting following error

    “Error Mapping incoming Response to .response_POST…..”

  21. Tirupathi Rao Merupula Tirupathi Rao Merupula

    Hi bro,

    In the example which you have in Manual creation of Rest Service, You have used POST method . How you are fetching the details of the Policy ID in Response. we need to use GET Method right for getting these values. POST method is not for Getting the values.

    Correct me if i am wrong.

  22. Giraj Giraj

    Hi Prem,

    Explained clearly.Nice article.
    One question here is how the response Json automatically get mapped to Clipboard.

  23. Sapthagiri Sapthagiri

    Hi Prem,

    Would like to thank you first for all the efforts you have put up in writing the post with detailed explanation. I do have a query and issue.

    Query : can Connect Rest (POST method) take XML as input parameters and send JSON as response.

    we do have a service developed in SAS with such configuration and its works from Soap UI. When tried writing the connect rule it fails in PEGA.

    I have posted the query in PDN as well . Here is the link

    Any suggestion would be highly appreciated

  24. Sudha Sudha

    Hi Prem,

    Thanks a lot for sharing your knowledge. It is very detailed and helpful.

    I have a scenario where I have to create a Connect-REST for Put Method. The REST service API returns only header but not body as Response. I am not able to upload the actual Response with only header in the Connect-Rest Wizard data Model Form. Please let me know if there is any way to handle the check and continue through wizard. Or manually creating the rules required is the only way.

  25. Ankit Ankit

    Hi Prem,

    While configuring Connect-Rest, Data Page and Data Transform are created. How to use the them?


  26. Ram Ram

    Hi Prem,

    Very informative post..
    Please help me to understand the below.
    In the above example,pega creates a data transform rule ‘FetchPolicyDetailsRequestGet’ and we are mapping the ‘Param.PolicyID’ value to ‘.request.query_GET.PolicyID’. Where we are configuring the value for ‘Param.PolicyID’.
    I hope you understand my question.

  27. Rama91 Rama91

    Hi Prem,

    When configuring Connect REST using service wizard , I am getting following Error.
    Any idea on this ?

    Evaluation problem(s) Rule evaluation failed : Canceling rule evaluation, java.lang.nullpointerexception.

  28. Gaurav Gaurav

    Hi Prem,

    Great Stuff… Excellent Article on Connect-Rest.
    Can you please create an article in Rest API provided by Pega . How to use them and how the external service uses the Rest API.

  29. Shivaprasad Shivaprasad

    Connection Flow Problem
    This is not applicable when transition is not handled in connector activity.
    Kindly Can you please understand me in more simpler way.?

  30. Ashiq Ashiq

    Really a Nice way of explanation of Connect-REST Method in Depth.

  31. Vishnu Vishnu

    How to pass array of properties as input request to connect rest in request tab
    for example, my json code is like below

    clipboard structure is like below

    partinfo–pagelits have 2 results

  32. Ajay Ajay

    for example
    if i have xsd as below
    how i can do property set for group block

  33. Ravikiran C Ravikiran C

    Awesome sir, thank you very much

  34. Sowjanya kanna Sowjanya kanna

    Hi Prem..
    How can we handle “Responce time” Exceptions.

  35. Hi Premkumar,

    Thank you so much for the knowledge sharing, those step by step screenshot make many Pega folks life way easier.

    Great Job !!


  36. Manoj yadav Manoj yadav

    Hi Prem,

    This post on Connect-rest Is is really very help full. If you could also share a post on differences between Put and Post in real time scenario.

    Thanks & Regard

  37. Matt K Matt K

    Love the site! I was able to get the Rest Connector to work, but I want to make a page list sourced from the rest connector to populate a drop down. Do you have any references for this?

Leave a Reply

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

error: Content is protected !!