How to configure Connect-REST in Pega?

Introduction

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‘ (http://myknowpega.com/2017/05/30/service-rest-step-step-tutorial/) 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”:

{

“PolicyType”:”Home”,

“PhoneNumber”:”9999999999”

}}

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  – http://myknowpega.com/Service/{INDIA} or http://myknowpega.com/Service/{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

Headers

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

Authentication

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

http://www.jsoneditoronline.org/

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

Review

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 🙂

Connection

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

Response

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 com.pega.pegarules.data.internal.clipboard.ClipboardPropertyStrMinFeatureImpl.getPageValue() 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.

FlowProblems

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.

Rule_Obj_Activity.pyInvokeRESTConnector.Rule_Connect_REST.Action

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.

32 thoughts on “How to configure Connect-REST in Pega?

  1. Hi Prem,

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

    1. 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. 🙂

  2. 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 ??

    1. 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. 🙂

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

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

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

  4. 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.. 🙂

    1. 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. 🙂

  5. 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?

    Thanks,
    Kumar.

    1. 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 🙂

  6. 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…

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

    Thanks

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

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

    1. 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 🙂

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

Leave a Reply

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