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)?
- 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.
- 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.
- The Service URL
- Request & response parameters
- HTTP method they host the service
- 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
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.
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.
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.
- 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.
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.
- Here you can specify the Integration class name, connect-REST name, ruleset name.
- You can update all 3 with the edit icon.
- 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.
- Connect – REST rule– FetchPolicyDetails
- Request page – request
- Response page – response_GET
- Data transform – Sets the request value
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.
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.
For all the 4 page property, pega creates 4 new classes.
Now request, response and class structure are ready.
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 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.
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.
Exactly same as Service-REST 🙂
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.
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.
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.
- End point URL
- Request, response parameter
- HTTP method
- 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
- 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.