Page |1

How do you configure Connect-File in Pega

Published May 13, 2017 by Premkumar G
34

What are the rules involved?

1. Connect-File.
2. Connector activity.

What is Connect-File?

 A connector rule falls under Integration-Connectors category.

 The main purpose of this rule is to create a file and place it in the
mentioned App server directory.

How to configure Connect–File?

 Create a new Connect–File rule from Integration category ( No wizard

available).

 Three blocks are there in the service tab.

1. File system

Destination Path : Provides a directory path of the App server. This is the path
where you can see your file.

File Name : Name of the file to be created.

If File Exists : If a duplicate file name is already there in the directory path,
then

a) Fail – End the connection

b) Append – Append to the end of existing file

c) Overwrite – Replace existing file

 Page |2

Enable BOM : True / False.

What is BOM?

Byte Order Mark. Whenever you save a notepad file, you may come across
 character at the start. These are useful to identify which byte order or
which encoding methods (UTF-8) are used. These will be used for decoding
purposes. Pega recommends enabling BOM, if CSV data are exported
to Excel.

2. File connection handling

Keep File Open : True / False

Imagine a scenario where you need to update the same file again and again
with different Connect-File methods. Check Keep File Open to true to enable
this function. Remember to close the file on the final Connect-File method.

3. Error Handling

This is same for all connectors. Holds the status value and message in
property values. Leave it as-is.

How to test the Connect–File?

After configuring, use Test connectivity button to validate the destination path
configuration.
 Page |3

If some error comes, then please check if the destination path provided is a
valid directory in App server.

How to invoke a Connect-File?

Method 1. Create a new connector activity and use Connect-File Method.

Connect-File method accepts 3 parameters:

1. Connector name – Provide the Connect-File name.

2. Operation – Many operations are available.

 Write from HTML stream rule (Copy the HTML content to file).
 Write from XML stream (Copy the XML to .xml file).
 Write from eForm (Used to create a PDF file).
 Write from work attachment (Used to move the work object attachment).
 Write from clipboard (Copy the clipboard property containing data to
file).
 Close file (Use this in last Connect-File method when keep file open is
true).

3. Parameter – Set parameter value based on the operation value you

select.

 Can refer stream, property , literals etc.

Method 2. From flow Integrator shape

 Flow –> Advanced Shapes –> Integrator utility.

 Use the activity same as above of type ‘Connect’.

How to debug the Integration?

Scenario: Create a text file containing string “This is a test String” and place it
in C:\TMP directory in App server path.

Step 1: Create the Connect-File as shown above.

 Page |4

Step 2: Create a new connector activity.

-Use Operation mode as “Write from clipboard property” with parameter set
from step 2.

Step 3: Manually run the activity and check the App server path C:\TMP

Note : In many applications only system administrator have access to Server.

Step 4 : Open the text file.

Where a file gets created ?

We can see that only 2 rules are involved in File Integration.

1. Connect-File.
2. Connector Activity.

You may get a question “Where the file gets created? How the mapping from
data source is handled?”

Ans: When the Connect-File method calls OOTB activity, Rule-Connect-

File.Invoke gets executed. The 500 line java step is solely responsible for
creating the file and moving to the required directory. No need to worry about
this activity.

Complete those two configuration points and Pega

does the rest.
 Page |5

How to configure Service-REST in Pega?

Published May 30, 2017 by Premkumar G
87

Introduction

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

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:

http://maps.googleapis.com/maps/api/geocode/json?address=Chennai

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

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

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.

{“SampleResponse”:

“PolicyType”:”Home”,

“PhoneNumber”:”9999999999”

}}

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

 Page |9

“PolicyType”:”Home”,

“PhoneNumber”:”9999999999”

}}

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.

 P a g e | 10

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

Servicetab
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
 P a g e | 11

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,

http://11.12.124.32:8080/<ServicePackageName>/ServiceClassName/Service
MethodName

Protocol://<HostName>:<PortName>/<Package>/<Class>/<Method>

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,

http://host:port/<ServicePackageName>/ServiceClassName/ServiceMethodN
ame/Policy/<PolicyID>

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.
 P a g e | 12

Now you can ask me.

What is stateful session?

Please go through the ‘Requestor types‘

(http://myknowpega.com/2017/05/13/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.

 P a g e | 13

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

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:

https://stackoverflow.com/questions/630453/put-vs-post-in-rest

DELETE Method

 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.
 P a g e | 14

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

 P a g e | 15

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?”

 P a g e | 16

Step 1: Update the service –REST rule.

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

Request

Response

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’.
 P a g e | 17

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.
 P a g e | 18

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.
 P a g e | 19

How to configure Service Package in Pega

Published June 2, 2017 by Premkumar G
47

Introduction

I will say Service package is the heart of Integration service rules in Pega.
On looking at the name, you can brief me about service package.

 Used to package services 🙂 Absolutely right.

Remember, the Service REST I created, it belongs to a Service package rule

– TestServicePackage

Imagine the Integration-Service rules as a robot 🙂

 Whenever an incoming request comes, they process the request and

sends the response.

Incoming Request –> Process the request –> Send the response

I am gonna pick the middle part. How do we process the request in Pega?
We need Pega rules, right? How can we run a rule in Pega?

Yeah, think about it.

Operator ID –> Access Group –> Application –> Rules

Services are not operators. So who gives them access to Pega rules.

1. Service Package instance provides the access.

This is not the only role Service package is being restricted to.

2. It can manage the Requestor sessions – Stateless/Stateful.

3. It can provide security by enabling authentication.

 P a g e | 20

4. It supports in deploying our services in other applications by

providing WSDL, portlet war, File etc.,.

5. It can manage the requestor pooling.

I am going to explain all the 5 functionalities, you can achieve in Service

Package rule.

What is a Service Package data instance?

 Define packages, provide access to listeners and support deployment.

Please go through the ‘Requestor types‘ post to learn about APP requestors.

How do we configure a Service Package data instance?

 Service Package instance belongs to Integration-Resources category.

Create a new instance.

Wait, where is the ruleset ?!

Cool, Service packages are data instances and don’t belong to any ruleset
versions. They are included in ruleset to support deployment in other
environments.

Once you have created a data instance, you can update the ruleset anytime.

Service Package data instance contains 2 main tabs:

1. Context tab
2. Pooling tab

Context tab
 P a g e | 21

Processing mode –

You have two options – Stateful, Stateless.

Let’s see some basics.

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

I am going to walk you through an example explaining stateless vs stateful.

Prerequisites:

Step 1: Create 2 REST service in same Service package.

Step 2: Populate a page from first service activity.

 I populated page MyKnowPega with pyLabel value as “Prem”.

Step 3: Configure the second service activity to just consume the value from
MyKnowPega page and set pyValue directly to response.

We have populated page in first service and are using the page in second
service.

First let’s test Stateless.

 P a g e | 22

Step 4: Set processing mode to – Stateless in service package rule.

Step 5: Directly ping the service URLs in browser one by one.

HIT first, then second.

Policy type is null. You know why? 🙂

Page is not maintained, since the package is stateless.

Let’s test Stateful.

Step 6: Set processing mode to – Stateful in service package rule.

Step 7: Now again hit the URL one by one.

You can see the response. We have reused the clipboard.

We have successfully tested the stateful & stateless session behaviour.

When do we use stateful?

In a purchase request case, you have exposed different API like –

GetPurchaseRequest, UpdatePurchaseRequest, UpdateOrder, MakePayment
etc.

 The clients need to make use of this one by one in order.

 P a g e | 23

 In this case, you can make the service package stateful, so that different
methods (API) can reuse the pyworkpage and process the requests.

Note: Select End Requestor in Last Service-REST rule. This is applicable

only when process mode is stateful.

Service Access group – As discussed in Introduction, it helps in locating

service rules.

Requires authentication – On enabling this, you will get few other options.

You can select an authentication type.

Basic – Verifies if the request contains Pega operator ID & password.

Custom – SSL/LDAP. On selecting this, you will be provided with an option to

select Authentication service rule.

OAuth – This is an advanced type of authentication. I love it.

An exclusive post on OAuth authentication is coming soon 🙂

Use TLS/SSL (REST only) – This is applicable only when,

1. Require authentication – True

2. Authentication type – Basic
3. Service – REST

You can access the REST only through TLS/SSL. It means

through https protocol. Secured one.

Methods
 P a g e | 24

This tab lists all the service methods included in this service package.

You have a drop down option to select service type.

Deployment

Deployment tab appears only for selected service types like SOAP, Java,
DotNet etc.,.

Deployment type will vary based on the service type.

SOAP – WSDL

Java – Java class (jar file)

You can select the service class and can optionally include the namespace
URI for SOAP service rules.

Deployment results

You can download the content from this link. Click on it.

You will contain the methods included in xml format. WSDL file.

Similarly for Service-Java, you can download the JAR file.

Pooling tab

This is the very interesting part.

Pega not only reuse the rules, they reuse the requestors too 🙂
 P a g e | 25

We know App requestors are involved in processing the service requests.

First, let me explain it with example.

Step 1: Log in the SMA and check the Requestor management.

Only 3 App requestors (starts with A) are available.

Scrolling issue, please adjust with the pics.

Step 2: Now hit our URL and check the requestor management page.

You will see a new requestor has got created to process the request.

Now let me relate with service package polling tab configuration.

We have configured as,

Max idle requestor – 10

Max active requestor – 10

Max timeout – 10s

Scenario 1: Assume, client sends a service request to Pega.

A requestor (active) gets created along with requestor Pool.

 Imagine 2 boxes. One Idle box and another active box.

 The requestor created sits in active box and process the request. After
processing the request, the requestors jump to idle box.

It is like when you have a work, you sit in Active box and complete it. Once
you completed the work, you can move to Idle box and relax. 🙂
 P a g e | 26

Idle requestors – 1 ; Active requestors – 0

Scenario 2: Now, when a second service request comes from the client
system.

 Pega effectively reuse the idle requestor for processing and it doesn’t
create a new requestor.
 This is how Pega effectively reuse the requestors.

Scenario 3: Say, you have got 3 requests coming at the same time.

 Pega checks the idle requestor and find only 1 in idle box. So it creates
2 new requestors to process the remaining requests.
 After completing all the 3 requests, the three requestors move to the idle
box.

Idle requestors – 3 ; Active requestors – 0

Scenario 4: Now assume, your application is most wanted and about 15

requests come at the same time from client systems.

 Pega reuses the three idle requestors and creates only 7 more new
requestors to process.
 Because, in service package rule, we configured the maximum active
requestors to be 10. The other requests will be in queue waiting for
requestors.

Maximum Idle Requestors – Specify the maximum requestors that can be

reused for new requests.

For example, imagine, already 10 ideal requestors are available in pool. When
a new active requestor completes processing the request, it needs to enter
ideal requestors pool, but quota is completed already 🙂

 You can specify Max Idle requestors ‘-1’, to allow unlimited idle
requestors.
 P a g e | 27

Maximum active requestors – You can specify how many requestors can be
allocated to process different service requests coming to services in service
package rule.

As discussed above, when traffic comes to your service (say 20 at the same
time), only 10 active requestors will be available to process the requests.

You need to take this criteria to define the max active requestors.

 You can specify Max active requestors ‘-1’ to allow unlimited active
requestors to process the requests.

Maximum wait (in seconds) – Specify the time before which a request fails
without processing.

For example, imagine already 10 active requestors are processing the

requests. (Service activity involves lot of DB connections, so service is slow to
process the request).

When a service request comes in, no requestors are ready to process the
request. So the incoming request can wait for some seconds. Once the max
wait time is crossed, the request fails and system sends the error to the client
system.

How to debug requestor pooling?

Step 1: Open SMA and go the requestor management. Note the App
requestors.

Step 2: Hit your service URL and check the requestor management page.

A new requestor is created.

Step 3: SMA -> Administration -> Requestor Pools

 P a g e | 28

You can see the service package name and all the configuration values for
requestor pooling.

Step 4: You can clear the requestor pooling.

On clearing, it will delete all App requestors that belong to the service
package.
You can verify in this same page as well as requestor management page.

Step 5: Let’s test with many incoming requests.

Note: You need to have a long running service activity 🙂 (Not advisable in
real). Like this.

The reason is the active requestors can process the service requests in
milliseconds and go idle. So it will be reused again and again 🙂

Hit the URL in browser continuously.

Step 6: You can see new requestors created to process the requests.

You can also check the requestor pools landing page.

Hope you understood the importance of service package rule 🙂

Things to remember:

 Service packages are data instances that support service processing in

Pega.
 They decide the processing mode as either stateful or stateless.
 P a g e | 29

 It provides security by enabling authentication for the service. The client

should send the authorization parameters to get serviced.
 It supports deployment by providing the deployment artifacts like WSDL
file, Jar file, etc.,.
 It manages requestor pooling for services.
 There is some exception like only Service Email don’t require Service
package as a key part. We will discuss about it more in Email
Integration topic.

Service package is a packet dynamite 🙂 Though the configurations

looks simple, it controls many Service Processing functionalities in
Pega
 P a g e | 30

How to configure Connect-REST in Pega?

Published June 7, 2017 by Premkumar G
63

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.

2. 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.
 P a g e | 31

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
 P a g e | 32

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.

 P a g e | 33

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

 P a g e | 34

 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
 P a g e | 35

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

 P a g e | 36

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.
 P a g e | 37

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

 P a g e | 38

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 🙂

 P a g e | 39

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.
 P a g e | 40

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.

 P a g e | 41

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
 P a g e | 42

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.
 P a g e | 43

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.
 P a g e | 44

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

 P a g e | 45

 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.ClipboardPropertyStrMinFeatureI
mpl.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.
 P a g e | 46

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.
 P a g e | 47

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.
 P a g e | 48

How to configure an email account & send outbound email

from Pega?
Published June 19, 2017 by Premkumar G
80

Introduction

First of all, let me briefly explain how an Email works?

We know we can login any email ID and send any email we want, but what
happens at the back-end?!

Think about, how mail processing work in post office?

Step 1: You are in Chennai and you write a mail to your friend in Bangalore

Step 2: You go to post office and post the mail. (Your job over here)

Step 3: People working in Chennai post office identify the recipient address
and the respective post office. Then they send the mail to Bangalore post
office.

Step 4: Bangalore post office receives the mail.

Step 5: Post man helps in carrying the mail to the recipient address. The job
ends here and your friend receives the mail 🙂

Scenario: You need to send an email from your personal Gmail ID to your
friend who use Yahoo ID

Let me relate the email processing with mail processing

Step 1: You logged in your Gmail ID – prem@gmail.com and sent an email to

your recipient address.

Step 2: The mail reaches the SMTP email server. Here I don’t use any proxy
network, so by default It reach the Gmail email server.
 P a g e | 49

Note: Email servers helps in relaying the email message to recipient

Step 3: SMTP Email server uses DNS to identify the Email server of the
recipient email address aarti@yahoo.com Yeah its Yahoo 🙂. It sends the mail
to recipient email server

Step 4: The recipient Email server receives the Email and they can use IMAP
or POP3 protocol.

Step 5: Finally the recipient – aarti@yahoo.com receives the email using any
one of the above protocol

 SMTP – protocol used for sending email

 IMAP/POP3 – protocol used for receiving email

In this post, we are going to send an outbound email.

What are the things required for you to create an outbound email
account?

1. You need to have an valid email address from a valid email providers
(google, yahoo etc)
2. You need to know the SMTP email server details

 SMTP server host name

 SMTP server port number

What is an Email account?

 Email account is a data instance

 It belongs to Integration resources category.
 Email account instance holds the account details both for outbound
(outgoing) and inbound (incoming) emails.

How do you configure an Email account instance?

Pega provides a simple wizard to configure an Email account.

Step 1: Designer studio -> Integration -> Email -> Email Wizard
 P a g e | 50

Step 2: Wizard starts. Enter Email Information.

What would you like to do? –

a) Receive an email and create a workobject – Use it for email service, when
we need to process the incoming emails

b) Configure an email account – To create an email account and use it for

outbound emails

Here we select – Configure an email account

Would you like to use the Default EmailAccount Key?

If you check this option, you can make this email account as default account –
Means a common account.

Why do we need a default account?

 Every email account can be tagged to a work pool. Actually, the email
account data instance name will be the same as the work pool name it
is tagged to.
 But it is not mandatory for every work pool to have an email account.

Say for example, I create a sales case in ‘OIKGGB-MyKnowPega-Work’

Workpool. I need to send the correspondence to the customer. But I didn’t tag
any email account to sales case workpool.

Now think Pega handles this? Before sending an outbound email from a case,
Pega checks If there is any email account tagged with the case work pool.

 If Yes, then Pega sends the mail from the email account.
 If No, then Pega sends the mail from Default email account.

Default Email account can act as a base (common) email account in a Pega
application.
 P a g e | 51

So, when you want to create a Default email account check the checkbox.

You can see the work pool selection disappears 🙂

Which work pool will be associated with this email account – you can
select the workpool from the dropdown.

 You can see a note message there.

 It means, if there is already an email account tagged to a workpool, then
this wizard just updates the email account and don’t create a new one 🙂

In this tutorial, we will create a new email account for the workpool ‘OIKGGB-
MyKnowPega-Work’

Click on next screen.

Step 3: In the wizard 2nd step, enter the account details.

Enter Account Info

Select email provider – provided with a link. You can click on and select an
email provider.

These are the email providers, Pega support.

 Here I am going to select – Google Gmail

 As soon as you select the email provider and submit, the connection
details are pre-populated in the sender and receiver blocks.
 P a g e | 52

First let’s fill the Identity info

Full name – Enter the full name of the Sender

From – Enter the mail ID, from which you will be send the email

User ID – If there is some email ID the SMTP host use, then specify the ID
there, else you can copy the same from ‘From’ field we used above

Password – Click on the link & enter the email Id password.

Reply To – You can enter a valid email address, so that recipients of the
outbound email can reply.

Connection

 This is where you configure the details about SMTP email server

Host (SMTP) – provide the host name of SMTP email server.

What are the things to note down, when configuring SMTP Host?

 Here I use personal edition & connected directly with internet. I don’t
have any proxy connection between. So, I use the Gmail SMTP host
‘smtp.gmail.com’
 If you are connected in any Organization proxy network, then you need
to specify the SMTP host of the organization email server not the Gmail
SMTP host

Inside proxy network, If you provide the Gmail host and test the connectivity,
you will get the below error

If you see this type of error, then please check with administrators and get the
Organization Email server host name 🙂 (this may occur, If the Gmail SMTP
server down too. This is very rare 🙂)
 P a g e | 53

Port – Enter the SMTP server port number.

Note: To make any connection to any server, you need an open port
connection.

There are three available SMTP ports

a) 25 – This is the default port used for transmitting mails between servers.
Introduced very long back, before I came into this world.

b) 587 – This is the recommended port to be used for SMTP communication.

It uses STARTTLS connection.

c) 465 – This port was introduced to support SSL means of sending email
messages. But the same can be done by 587.

What port to choose 25 or 587 or 465?

 25 – This is still used by many email servers around the world. This is
mainly used when we need to relay the emails between different email
servers. The main drawback is this can be exploited to spread spam &
malware

Note: If you use Organization email server(proxy network), then you need to
get both the host name and port number from the administrator

 587 – This is highly recommended port and use STARTTLS connection.

STARTTLS can initiate a TLS/SSL connection and secure the
messages. Approved by authorities.

 465 – This was introduced to support SMTPS connection, secured way

to transmit messages but not lived up to the expectation. Still some
email servers open up the 465 port for SMTPS connection. There were
some fear that this port can be brought down.

Note: My advice (If no proxy network) go with 587 port to connect email
servers

Use SMPTS? –
 P a g e | 54

 You can select this option to secure the email message.

 When selected, you need to use port number – 465

As I mentioned before, this is not recommended. Port 587 can secure the
message.

I am going to use port 587

Message signing –

Why do we need message signing?

 The email servers help in relaying emails. If they don’t use secure
connection, then there is a possibility that the email can be read by
hackers.
 To encrypt the email.

How do we do it?

Step 1: You need to get the help from companies that offer digital certificates
(.jks or .pfx )

Digital certificates – they are the public and private keys which can be shared
only with the recipient to decrypt the email

Step 2: Create a keystore instance and upload the .jks file

Step 3: Include the keystore instance in the message signing section email
account.

 Now your message is digitally signed.

Note: You need to share the key with the recipient to decrypt the email.

Receiver

Though we are going to configure mail ID only for outbound, we need to fill out
the receiver section too for inbound email to avoid wizard validation.
 P a g e | 55

Identity

User ID – Same as sender fill the email ID to receive the incoming emails

Password – Input the password for the User ID you use above.

Connection

 Here we can use two protocols – IMAP, POP3 protocol

Note : At this point, the email is available in the receiver email server. Now
the receiver mail client ( mail ID) needs to access the mail from the server.

What is the difference between IMAP & POP3 protocol?

Say you have synced your mail ID s in both mobile and laptop.

POP3 –

 When you access the Gmail to check the mails from laptop, the mail
gets downloaded in the laptop and gets deleted from the email server.
So when you try syncing from mobile, you will not find the mail.
 It use 110 (unsecured) , 995 (secured) port numbers

IMAP –

 When you access the Gmail to check the mails from laptop, the mail still
resides in the mail server and will not be deleted.
 It use 143 (unsecured) , 993 (secured) port numbers

Always try to use IMAP protocol to receive the email.

Host Name – you can specify the receiver emailing server hostname

For gmail – imap.gmail.com / pop3.gmail.com

Note: As we saw before in sender section, If the client receives the mail inside
proxy network organization, you need to get the hostname port number from
the administrator.
 P a g e | 56

Port – Always try to use secured ports

IMAP – 993; POP3 – 995

Use SSL/TLS – You can use SSL/TLS connection to receive the email

Advanced parameters

 There may be situation to modify some properties in receiving servers.

You can add those parameters here.

For example, when you use Microsoft exchange servers to receive the
incoming email, you need to disable plain authentication

Key – mail.imaps.auth.plain.disable; Value – true

Note: Consult with administrators and complete it with care 🙂

 Huh! Let’s move to next screen. Click next on the wizard

Step 4: You can review the details in this screen.

 After reviewing click on next

Step 5: You can see the email account created in the confirmation screen.

 Click on done to close the wizard.

Let’s open the Email account instance.

 You can see all the details completed from the wizard.
 Use the test connectivity button at the top to test the connection.
 P a g e | 57

 We get an authentication problem.

 This is because in Gmail application, they don’t allow less secure
apps to access them.
 In my case I use personal edition and it is a less secure app.

How to enable Gmail to allow less secure apps?

Step 1: login the email Id, you provided in the sender information.

Step 2: Click on your profile pic in top right corner and open My account.

Step 3: Click on Sign-in & security.

Enable Allow less secure apps ON.

Step 4: Test the connectivity button again.

 You can also test by checking SMTPS connection in port 465.

 This is because Gmail servers open up both the ports to receive the
incoming email.

Now the mail account is ready to send any mail to anyone from Pega 🙂

It’s time to test what we developed.

What are the pre-requisites to test an email account?

a) Create correspondence rule

I created a simple correspondence rule – Greetings.

 P a g e | 58

b) Create a simple flow rule in the workpool class – ‘OIKGGB-MyKnowPega-

Work’

How to test the outbound email?

Step 1: Open the flow rule and add a Send Email shape from smart shapes
palette.

Step 2: Double click on the Send email shape and configure the properties.

Step 3: Save & run the flow.

You can see the mail successfully attached with the case.

Step 4: Login the mail ID & verify.

Things to remember

 Have a valid email ID & password

 If you are connecting from proxy organization network, then get the
Email server host name & port to connect.
 For SMTP protocol, prefer 587 port number (STARTTLS) over 465 port
number (SMTPS)
 For receiving mail prefer IMAP over POP3

Email Integration is very simple to configure.

You can follow the above steps in the post and try sending email from
Pega 🙂

Have fun !!!

 P a g e | 59

Configure Service SOAP in pega

Published August 2, 2017 by Premkumar G
35

Introduction

In this post, we will see how a Pega system host a SOAP web service.

Hope, you went through my post on Service REST Integration.

Please go through the below link to get some basic detail about services in
Pega.

http://myknowpega.com/2017/05/30/service-rest-step-step-tutorial/

What is SOAP?

SOAP – Simple Object Access Protocol

 Web services help in communication between different systems via

World Wide Web – preferably HTTP protocol.
 SOAP is a protocol.. no no a standard protocol 🙂
 SOAP service use XML as messaging format and HTTP/SMTP protocol
for transmission.

Service-SOAP is very easy to implement, when you have some basic

knowledge about WSDL files and XML mapping rules!!

I suggest you to go through my previous posts on WSDL and XML mapping

rules before proceeding 🙂

http://myknowpega.com/2017/07/04/wsdl-structure-relation-pega-rules/

http://myknowpega.com/2017/07/18/xml-mapping-rules-xml-stream/

http://myknowpega.com/2017/07/18/xml-mapping-rules-extended-parse-
xml/
 P a g e | 60

How do we configure Service-SOAP?

First let’s see the requirement scenario

 Pega system needs to host a web service – GetCustomerDetails.

 Other system will send the CustomerID as request and Pega will
respond them with all the details ( Policy, address) corresponding to the
customer ID

Request – CustomerID

Response – Customer Name (single value), Policy details (page list),

Address details (page)

Pega makes the process simple :). We got a wizard to implement SOAP
service in Pega.

What are the rules required before running Service SOAP wizard?

1. Primary class – It can be integration class, work class or any data class
( No need to create a new class, if you can reuse any existing class)
2. Properties – Request and response data model properties. ( No need to
create new properties, if you can reuse existing properties)

Let’s go and create the pre-requisites 🙂

Step 1: Create a new Integration class. – TVS-Int-GetCustomerDetails

Step 2: Create the request, response properties

First let’s create 2 page properties – Request & Response.

Note: We know page properties should contain page definition.So, create two
classes for request and response.

Request – TVS-Int-GetCustomerDetails_Request
 P a g e | 61

Response – TVS-Int-GetCustomerDetails_Response

Request –

 Similarly create a one for response – Response with response class as

page definition.

Click on the application explorer and check the main integration class. You
can see the request, response page properties.

Skeleton is ready! Go on and create the individual properties.

 Create all the required properties and page definition classes.

Once you created all the above properties, you can again go and see the
data model structure from App explorer.

We have created all the main pre-requisites for Service SOAP.

How to implement Service SOAP using wizard?

Designer studio -> Integration -> Services -> Service Wizard

Step 1: You will be landed in the first step of wizard.

Select service purpose

 P a g e | 62

Service purpose – You have 3 options

a) Create and manage work – Use this option, when the service wants to
create a new workitem

b) Invoke existing activity rules – In some scenario, the service activity can be
existing activity.

Say for example, you already have an activity that accepts customer ID and
returns all the customer details. Kind of search screen in user portal. You can
make use of that same activity in Service SOAP rule. Here you can use
‘Invoke existing activity rules’ option

c) Process input or output data – Use this option, when you need to make use
of the input data and perform some process (no existing activity is reused as
service activity).

Note: You can use this option to do whatever we want :).

Remember, there is no restriction that we should always choose certain

service purpose.

Here I select, Service Purpose – Process input or output data

 For all the above three service purpose, the main difference is service
activity.

Create and manage work – Wizard creates a service activity, which includes
steps to create a new work item.

Invoke existing service activity – No new service activity is created. Service

activity = existing activity

Process input or output data – Wizard creates a empty placeholder activity.

You can customize it 🙂

Service Type –
 P a g e | 63

 Pega provides the same wizard for different service types. Steps vary
based on the service type.
 Select – SOAP and click next.

Step 2: Select the data class

Data class – Don’t confuse it with data type (Data-) class 🙂

 Data here refers to input output data. You can provide the Main
integration class here, which contains the input, output properties. ( You
can also provide any class)

Remember – TVS-Int-GetCustomerDetails is the main integration class.

Service name – Choose a name for the service that will be generated.

 You can specify the Service-SOAP rule name

 Here I choose GetCustomerDetails.

Click on next step

Step 3: Customize service data

In this step, we will determine the request, response data structure.

Remember, we already created the data model structure for request and
response.

Request structure
 P a g e | 64

 All the properties which come under data class (TVS-Int-

GetCustomerDetails), will be listed here.
 You can select the request properties using checkbox.

In our case, we have a simple request – Request.CustomerID

Do we need to use XML for this data mapping??

Since it is a simple request, we don’t need any XML structure. But keep in
mind, in future if we need to add more complex properties, then we can use
XML for data mapping.

For testing purpose, we will use XML for data mapping.

Response structure

Same like request structure, you can select the response properties 🙂

You can see an additional checkbox – Return process info XML data

What does it mean?

 It is applicable only when service purpose is ‘Create and manage work’

 On selecting this option, system returns XML stream about the work
item and assignment status.

We will leave it cleared 🙂

Step 4: Select service resources

What are the service resources?

 P a g e | 65

1. Ruleset name – you can specify any ruleset – preferably integration

ruleset.

2. Ruleset version – specify the version

3. Service package options – you have 3 options.

a) Configure a new service package – Creates a new service package

instance

b) Copy an existing service package – creates a new service package by

copying the details from existing service package

c) Use an existing service package – You can make use of any existing
instance

Step 5: configure data records

The only data instance, we create here is service package data instance. So
it’s obvious that we will be configuring service package data instance.

Please go through the post on service package data instance to get to know
about all those configurations.

http://myknowpega.com/2017/06/02/service-package-configuration-tutorial/

Click next.

Step 6: Review screen

You can see totally 4 rule instances and one data instance got created.
 P a g e | 66

1. Service-SOAP rule
2. Service activity
3. Parse XML rule
4. XML Stream rule
5. Service package data instance

Click on Finish to complete the wizard.

See how simple the wizard steps are 🙂

Let’s analyze the rules one by one

What are the configuration points in Service-SOAP rule?

It has 6 main tabs.

1. Service
2. Request
3. Response
4. Faults
5. XML Page
6. Advanced

Service tab

 This tab look more or less same as Service-REST rule – service tab

Please go through the below link for more details on Service-REST.

http://myknowpega.com/2017/05/30/service-rest-step-step-tutorial/

Primary page

Primary page class – data class used in the wizard.

Data transform – You can use a data transform, to initialize some properties

Page name – Default service page name – MyServicePage – primary page.

 P a g e | 67

Service activity

Activity name – You can specify the service activity name and its parameters,
if any.

Style and Use

You can specify one of the three options here.

a) Document / Literal
b) RPC / encoded
c) RPC / Literal

What is the difference between RPC and document?

 Document style model is used when the SOAP message body is XML
instance. Use RPC when the SOAP message body is simple data type
(string).
 So in document style, we send message as discrete elements where as
in RPC style message send as XML content.

You have two models to use for the above styles.

1. Encoded
2. Literal

So totally 4 style combinations are available

1. RPC Encoded –This is deprecated. Use to support legacy services

2. RPC literal -Use it when the request is simple parameters (Can be
directly mapped from clipboard)
3. Document Encoded –Not applicable in Pega
4. Document Literal –Use it when the request is in XML format.

For more info – Please go through the WSDL structure post.

http://myknowpega.com/2017/07/04/wsdl-structure-relation-pega-rules/
 P a g e | 68

Processing options

Enable MTOM? – Pega use this option by default

What is MTOM?

 Message Transmission Optimization Mechanism

 It provides an optimized way of sending the binary data to and from
systems.

Please follow the below link for more details

https://stackoverflow.com/questions/215741/how-does-mtom-work

End requestor when done? – same as service Rest.

Method is read only – Leave cleared.

Execution mode –

a) Execute synchronously – process the request and return the response

synchronously

b) Execute synchronously (one –way operation) – process the incoming

request and send no response message content. Response will contain only
HTTP code like ( 200 – for success ; 401, 500 etc for failure)

c) Execute asynchronously (queue for execution) – Queues the record for

background processing. Returns the Queue Item ID as synchronous
response.

We will see about asynchronous processing in separate lesson 🙂

d) One – way operation (queue for execution) – queues the request and return
only HTTP response code.
 P a g e | 69

Request processor – Specify the Service request processor instance for

parallel processing.

Request tab

SOAP action URI – you can specify the SOAP action HTTP request URI

Request headers

Data type – It can be either string or XML literal.

 You see Map to can be of – Clipboard, Parse rules, RequestorID ,

Username, Password or can be a function ( Parse thread topic header –
used in email service)
 Requestor ID – you cannot enter Map to key value here. Used to
support stateful sessions
 Username / Password – You cannot enter Map to key value – Used in
authentication.

Cool you don’t use those much. Often you end up using either Clipboard or
XML Parse rule.

Request parameters

Data type – SOAP request body supports wide variety of data types.

Map to – it can be either Clipboard or XML parse rule.

In our example, Wizard created a Parse XML rule and it is populated in the
Service SOAP.
 P a g e | 70

Response tab

 Response tab is more or less similar to request tab .

 You can see XML stream rule is involved to convert the clipboard data
to XML message content.

Faults tab

How to handle exceptions in Service SOAP?

The answer is fault tab 🙂

You can have 5 types of fault conditions.

a) When – You can specify a when rule to check any error conditions, If true
system returns the fault message specified.

Note: When anyone of the fault condition evaluates to true, then system
returns the fault message alone. Only if all fault conditions are false, then
system returns the normal response message.

b) Queue When – There may be some situation, where the service activity
needs to obtain a lock to process the request. If the case is already locked by
other user, then we can queue the request for ‘Service Request Processor’
specified in the Service tab for background processing.

 Service returns the Queue Item ID as response.

 No need to explicitly map the queue item ID – Pega cares it J

c) Mapping error – When there is some mapping error between incoming

request message and clipboard, then we can return a fault message.

d) Security error – When the incoming request fails authentication, then we

can return a customized fault message.
 P a g e | 71

e) Service error – If there is some other problem with service, then we can
return a service error fault message.

When Key – If the condition is when or queue when, you can specify a when
rule here.

Map from, map from key are same like request response tab

Fault detail key – used to return the fault message in XML stream

XML Page

This is always a mystery tab 🙂

 The actual purpose of this tab is to map the incoming request proeprties
to a page specified. Data transform helps in setting the proeprties.
 Key point to note here is we don’t set any value in the data transform 🙂

I am still searching in which scenario, we use it.

If someone comes across it in any project, please clarify me !!!

Advanced tab

Web service security

 This helps in enabling security for the web services.

Enable ws security – You can check it to enable.

Security profile – You can specify a WS security data instance here.

 WS security ensures the message are transmitted securely between

applications 🙂
 P a g e | 72

Request parse XML

Go through my post on Parse XML to get to know more details.

http://myknowpega.com/2017/07/18/xml-mapping-rules-extended-parse-xml/

Response XML stream

Go through my post on XML Stream to get to know more details.

http://myknowpega.com/2017/07/18/xml-mapping-rules-xml-stream/

Service activity

You can build any business logic out there.

 For testing purpose, I hard-coded the response 🙂

Service package data instance

 You can see the service SOAP is included in the Service package
instance.

For more details on service package instance, please follow my below link

http://myknowpega.com/2017/06/02/service-package-configuration-tutorial/

 You can see the WSDL file created for our Service SOAP

click on the WSDL file, you will find the WSDL source.
 P a g e | 73

Please go through my previous post on WSDL file J

http://myknowpega.com/2017/07/04/wsdl-structure-relation-pega-rules/

Now everything is ready :). Let’s go and test the service.

How to test the Service – SOAP?

Step 1: Open the service SOAP rule

Step 2: Go to Other Actions button -> Run the rule.

Step 3: Execute the service.

Shall we test the exception handling?! 🙂

Step 1: In the faults tab – Handle fault condition for security error.

Set constant error message – “Test Auth failed”

Step 2: Open the service package and ensure – basic authentication is

enabled.

Step 3: Now manually run the Service-SOAP.

In the requestor context – select Initialize service requestor context and make
the user ID and password empty.

Step 4: Now execute the simulation request.

 P a g e | 74

You can see the exception is handled for authentication error 🙂

What are the things to remember?

When you host a SOAP web service, you are the boss. You decide
everything!!

 Have some detailed analysis about the service requirement and decide
the request, response structure.
 Once you confirmed all the required and response structure, you need
to create all the request, response data model and the integration
classes.

Once all pre-requisites are ready, go ahead and start the wizard.

Decide your service purpose –

I suggest you to use the ‘process input or output data’ option. It’s a 3 in 1
option 🙂

Select your data structure. You can use XML mapping rules.

Complete the wizard.

 Once you complete the wizard, you can verify all the rules.
 Open the service package data instance and check your Service is
included.

You can also verify the WSDL file.

 You can provide the same WSDL file to client systems, so that they can
make use of your SOAP service.

Hope you are clear with the Service SOAP basics 🙂

Catch you guys in my next post!!

 P a g e | 75

Connect SOAP in Pega

Published August 21, 2017 by Premkumar G
54

In this post, we will see, how to configure Connect-SOAP in Pega.

Please go through my previous post on Service SOAP

Configure Service SOAP in pega

 I will be consuming the service hosted by Service SOAP example in the above
post 🙂

Before that let’s get some basics about SOAP

What is SOAP?

– Simple Object Access Protocol

What are we doing in the above pic!?

We are sending the request to access the customer details – Object accessing

Object – Customer details

It is simple protocol 🙂 ( Really :D)………………….. SO it is SOAP

– SOAP is a web service.

What is a Web service?

 It is service that supports communication via World Wide Web

 Machine to Machine communication, by transferring the message in machine
readable formats like XML or JSON
 SOAP and REST are the commonly used Web services

Let’s see a scenario, where we can use a SOAP service 🙂

We know that an organization can contain different applications running on different

languages in different platform.
 P a g e | 76

Consider any Insurance organization – Let’s call it as “XYZ”

Imagine there are 2 main process – Quote creation and Policy creation.

 Quote creation is handled by Java application

 Policy creation is handled by dotNet application.

Now XYZ organization planned to provide some good customer support.

So Obviously, they have to Seek Pega help to provide the Customer service solution (
CRM product): D.

Now we have 3 applications

 Customer service handled by Pega application.

Now say a customer called customer service application and need to create a new
policy. What will you do here?

Two approaches are there

Approach 1: Replicate the policy creation process in pega application (build all the
required rules, cases etc)

Approach 2: make use of the existing policy creation process handled by dotNet
application.

What is your suggestion 🙂 Re-USE.

 It means we need to communicate with the dotNet application and tell them to
create a new policy.
 To achieve this, a web service should be hosted in dotNet application and
exposed, say Policy Creation service.

Pega application will be consuming the service.

 We see now many new pega application prefer using REST web service over
SOAP service

Advantages of REST over SOAP – I have explained in details in my Service-REST

post.
 P a g e | 77

How to configure Service-REST in Pega?

Let’s see what are the advantages of SOAP over REST 🙂

1. SOAP is a standard protocol. Everything is predefined in a standard WSDL file.

WSDL file includes all the required details to create a new SOAP integration. In REST
JSON files are used to create only the input output data structure. We need to get the
other details from the service providers.
2. Security – In addition to SSL , authentication security SOAP provides WS
security. REST don’t support WS security. SOAP is more secure than REST.
3. SOAP can use HTTP/HTTPS or SMTP other means of transport layer protocol
whereas REST depends only on HTTP/HTTPS protocol.
4. SOAP supports two phase commit, whereas REST don’t support.

We can see some common terminologies used in SOAP

SOAP Nodes – Between sender and receiver, there can be many nodes used in
transferring the SOAP mesage. All those are called SOAP nodes.

SOAP Message – Information that can be communicated ( Policy details) or

transferred between nodes.

SOAP Envelope – It encloses and identifies the SOAP message. Mandatory

SOAP Header – A SOAP header can contain one or more blocks. Each block can
identify individual receivers. Optional

SOAP Body – Contains the body of the message. Mandatory

SOAP Fault – when any particular node fails to process the SOAP message, the error
details are stored in Fault content as a SOAP body child element. Optional.

WSDL File – XML based language. External system use this WSDL file to describe the
web services available. They provide a standard way for web service providers and
consumers to work together.

 Please go through my previous post on WSDL file basics. It will be really helpful
proceeding further.

WSDL Structure & its relationship with Pega rules

 P a g e | 78

How to implement Connect-SOAP Integration?

First we will see the requirement scenario

We will be using the same scenario, we used for Service SOAP 🙂

 The external system hosts a Web service – GetCustomerDetails. Here the

external system is the same Pega application.
 So here we will be configuring a Connect-SOAP to consume the
GetCustomerDetails.

We will see the Customer ID as request parameter and get all the customer details as
response.

Request – CustomerID

Response – CustomerName (Single Value), Policy Details (page list), Address

Details (page).

What are the basic parameters required from the service providers to consume the
service?

a) Services – Describe the WSDL file service name.

b) End point URL – Address location

c) Operation – We know that single service can contain more than one operation.
GetCustomerDetails.

d) Style / Use – Document / Literal

e) Message

Request – GetCustomerDetailsRequest

Response – GetCustomerDetailsResponse
 P a g e | 79

f) Request, response data model properties

You see all the details are available in the WSDL file 🙂.

If you don’t’ have a WSDL file, then do the following. You don’t want to create
any properties or classes manually 🙂

Step 1: Open any starter flow.

Step 2: Go to Design tab -> Generate services. Click on it.

Step 3: It opens the service SOAP wizard. You can just follow the wizard steps and
complete it.

You will end up having a valid WSDL file 🙂

Note: The Integration wizard can consume the WSDL file and make use of some
existing OOTB activities to create the integrations. All process are automated by the
wizard.

What are the pre-requisites to configure Connect-SOAP?

Like Service-SOAP, we don’t want to create any Integration class or data model
properties prior. Wizard takes care 🙂

To use wizard, we need the WSDL file from the service providers. This is the only pre-
requisite.

How to use the Connect-SOAP Integration wizard?

 Pega provides a simple wizard to create the Connect-SOAP Integration rules.

Step 1: Designer Studio -> Integration -> Connectors -> Create SOAP Integration

Step 2: You will be landed in the wizard first screen.

Now the wizard process starts!

Step 2.1: Load WSDL

 P a g e | 80

Please go through my previous post on WSDL files – top to bottom explanation 🙂

WSDL Structure & its relationship with Pega rules

You have two options to load the WSDL.

a) Upload WSDL via URL

b) Upload WSDL from file

Note: WSDL document can be downloaded and available in local machine or it can be
hosted in another server.

Upload WSDL via URL

 Here WSDL file is available as an URL and hosted in different server

 You can use the URL to access the WSDL file.

Most probably, the external app servers will be secured using credentials. So when you
use this option, you may be prompted to provide the credentials.

Upload WSDL file

 Here WSDL file pre-downloaded in my local system.

I will explain, how I saved the WSDL file from the service-SOAP.

Step 1: Open the service package data instance and check the WSDL file.

Step 2: click on the WSDL file and save the contents in note pad WSDL file.

Step 3: WSDL file is available in my local folder.

Let’s get back to wizard.

 Use the browse option and load the WSDL file.

Click on next.
 P a g e | 81

Step 2.1: Select Operations.

You can see all the details are populated from WSDL file 🙂

Service Name – ServicesService

Port name – ServicesPortSOAP

Endpoint URL – URL specified in the WSDL file

Operation – GetCustomerDetails.

Note: You can test the service prior using test button. Click on the test button.

Click on next.

Step 2.3: Review

Integration layer – You can specify the Integration class integration rule set here 🙂

Context – I have specified to create a new Int ruleset. You can make use of any
existing ruleset.

 Click on preview records to verify the records the wizard create.

 Looks simple right!!

 5 types of rules will be created. Now click on create to finish the wizard.

You can see the confirmation screen for the wizard.

 P a g e | 82

What are the rules created with SOAP wizard?

1) Integration class

You can see the wizard created 8 classes.

 TeslaVeh-Int-GetCusDetails – Service class

 TeslaVeh-Int-GetCusDetails-ServicesService – Main integration class that
holds the main request response, response properties, Connect-SOAP and
integration mapping rules – XML Stream, Parse XML

We know page type properties refer to some page definition. Other classes basically
support these request, response data model properties.

Let me expand the main integration class.

 You can see all the main integration rules – properties, connect-SOAP, XML
stream, Parse xml rule are included

2) Data model properties.

 You can see the data model for the request, response properties.

You can open and check all the properties.

There are 6 page type properties and so 6 page definition classes.

3) Connect-SOAP rule – GetCustomerDetails

Where can you reference a Connect-SOAP rule?

 Activity – You can use Connect-SOAP method in a activity to invoke the SOAP
integration.
 Integrator shape in flow rule – Connect-SOAP method -> Connector activity ->
Integrator shape -> Flow rule. You can invoke the SOAP integration inside a flow
rule.
 P a g e | 83

 Data page – You can load the Connect-SOAP response as the source for any
data page

There are 6 main tabs.

a) Service
b) Request
c) Response
d) Faults
e) Advanced
f) WSDL

Service tab

Service Properties – You can see all details are just populated from the WSDL file.

Style and Use – Document/Literal

You have 3 options here.

a) Document / Literal
b) RPC / encoded
c) RPC / Literal
What is the difference between RPC and document?
 Document style model is used when the SOAP message body is XML instance. Use RPC
when the SOAP message body is simple data type (string).
 So in document style, we send message as discrete elements where as in RPC style
message send as XML content.
You have two models to use for the above styles.
1. Encoded
2. Literal
So totally 4 style combinations are available
1. RPC Encoded –This is deprecated. Use to support legacy services
2. RPC literal -Use it when the request is simple parameters (Can be directly mapped from
clipboard)
3. Document Encoded –Not applicable in Pega
4. Document Literal –Use it when the request is in XML format.
For more info – Please go through the WSDL structure post.
http://myknowpega.com/2017/07/04/wsdl-structure-relation-pega-rules/
Method Name – Operation name populated from the WSDL file – GetCustomerDetails
Namespace URI – Populated from the WSDL file. Optional
SOAPAction Header – Refer to the header request message. Populated from the
WSDL file. Optional
 P a g e | 84

Request only – there many be some situation, when we need to send only the request
message and don’t expect any response from the service. In such case, you can check
this option
True – Asynchronous. Once system sends the request, connection is terminated.
False – Synchronous. System waits for the response.
Authentication

 If the service providers, expect any authentication, then you can use this option
to authorize the request. You can use an Authentication profile instance to
configure the authentication credentials.
 We will see about authentication in separate post 🙂

Connection

Service endpoint URL – This will be populated from the WSDL file – Address location
value.

 This is the URL, where the service is hosted. You need to hit the URL to make
use of the service.

Response timeout – In milliseconds. This is a key area that supports synchronous

response.
Imagine an external document application hosts a web service. The web service
expects the document names as request and zip all the documents in a single file and
send the document name as response. Now say, you have requested to zip 1000
documents. Here the service may take some time to zip 1000 records ( huge size). It
means it takes some time to get the response.

 So how long can we wait for a response. It all depends on the business
requirements.
 If you want to wait indefinitely for the response, you can have the value as “0”or
null (leave empty). Else you can specify a certain interval in milliseconds. Once
the timeout is reached and the service returns a timeout error.

Connection ID / maintain session? –

This is applicable for stateful sessions with the service provider.
Please go through my previous post on stateful vs stateless sessions 🙂

How to configure Service Package in Pega

 P a g e | 85

 In short, stateful sessions are used to maintain the same session for logically
related connectors. Same session refers to sharing clipboard pages.
 You can have a connection ID, kind of token that can be used in all the logically
related connectors.

Maintain session ? –

True – session is maintained. The clipboard pages are not cleared

False – If this is the last connector in the logically related connectors, then uncheck this.
So the session will not be maintained. Clipboard pages will be cleared.

Error handling – Same as all connector rules.

pyStatusValue – Holds the HTTP code. 200 for success and other codes for failure

pyStatusMessage – success message or error message

Error handler flow – You can make use of a flow to handle error.

Say for example, You have created a case and using the connector in the flow rule. If
the service fails, we can make use of this connection problem flow to handle the error.

Invocation exception property – Java object to hold the jave exception stack.

Processing Options

Intended for –

a) Immediate execution – synchronous execution. The connector activity waits for

the service response.
b) Queuing – asynchronous response. The calling activity continues without waiting
for results. The Connect-SoAP queues an entry to background processing.

Asynchronous processing is a complex topic. I will explain it in a separate post 🙂

Request Processor – You can specify a connect request processor instance to support
synchronous processing.
 P a g e | 86

Request tab

This is same as all connector rules.

Request header –

Some service can expect some fields in the request headers. For example –
authentication parameters. We can set those fields, in the request headers.

You can either map from clipboard, constant ( simple request headers) or XML Stream
for complex request headers.

Request parameters – Specify the body of the SOAP message.

Data type – You will have a variety of data types to choose from

This is same as all connectors 🙂

Response tab

SOAP envelope content – If you need to capture the entire XML response content,
you can use this option. Specify a single value property to hold the entire xml content.

Response Headers – Same as request tab

You can parse the response headers.

Response parameters –

 You can specify a method to parse the response body message.

 P a g e | 87

 Same as request tab.

Faults tab

This tab is used to record the SOAP fault code and details. All the fields are defaulted to
standard properties.

 We already error handling in service tab is used to handle the exception cause
by Connect-SOAP method.

So what is the use of Faults tab?

 When there is SOAP fault return by the web service, then this tab will be useful
to capture the Fault details.

The common fault code is ‘VersionMismatch’ SOAP 1.1 – SOAP 1.2

Please follow the link and search ‘fault code’ to know more details

http://www.w3.org/TR/2007/REC-soap12-part1-20070427/

SOAP envelope content –

Target property – single value property to hold the entire content of SOAP envelope
that contain the fault message.

Fault Message fields.

Fault code property – single value property to hold the SOAP fault code

Reason property – single value property to hold the SOAP fault reason

Detail property – single value property to hold the SOAP fault details

Advanced tab

This tab is pre-populated when you create a new Connect-SOAP

 P a g e | 88

This tab is mainly used for following reasons

a) To update the AXIS, SOAP, HTTP versions

b) Web services security configuration
c) SOAP service header field configuration
d) Compensating action configuration

Client properties

Axis version – It can use Axis 2 / Axis 1.2.1

SOAP Version – Based on the binding port in the WSDL file, this field will be auto-
populated

 SOAP 1.2 – Binding port SOAP 12

 SOAP 1.1 – For ports other than SOAP 12

HTTP Version – It can be HTTP 1.0 / 1.1

This will be based on service provider server compatibility.

Enable MTOM? – We know that SOAP messages involve many nodes between sender
and receiver.

 This mechanism helps in effective transmission of binary data to and from web
services.

Secure protocol configuration

Lowest allowable SSL/TLS version – For connection with HTTPS end points, we can
determine the secure protocol.

It will be defaulted to highest TLS version.

Web service configuration

 This is used to secure the SOAP connection.

 P a g e | 89

 You can make use of either WS-security instance or web service policy instance
to secure the connection. We will see more in details in separate post.

WS-Addressing

 Address the SOAP header fields. This will be pre-populated by the wizard.

Compensating action and data

This block helps in executing some action, when the connector rule succeeds in
receiving the response.

 This is mainly used with work item page context.

Say for example, imagine purchase request case invokes GetCustomerDetails and the
service returns a valid response. In this case, we can use an activity to run on
pyWorkPage and can execute any compensating action.

 Compensating action can be another service call to get the Policy details
‘GetPolicyDetails’.

Compensating action data – Used to send the parameters.

Mostly you wont update anything in advanced tab and accept the values defaulted by
the SOAP wizard.

I never used compensating action 🙂.

WSDL tab

 This is the read-only tab.

 You can find the source of the WSDL content, from which we created the new
Connect-SOAP.Remember the wizard first step.
 You can load the WSDL data either from the WSDL URL or from WSDL file
(data) loaded from local drive.

4) XML Stream rule

 P a g e | 90

You can see the XML stream rule created by the wizard – GetCustomerDetailsRequest

For more details on XML Stream, you can visit my previous post

XML Mapping rules – XML stream

5) Parse XML rule

You can see the Parse XML create by the wizard – GetCustomerDetailsResponse

For more details on Parse XML rule, you can visit my previous post

XML Mapping rules extended – Parse XML

How simple is this 🙂. We have successfully created all the Connect-SOAP integration
rules using SOAP wizard.

How can you undo the wizard creation process and delete all the rules created by
the wizard?

Step 1: Designer studio -> Integration -> Tools -> Wizard cleanup

You can see, whenever you start a wizard Pega creates a work item using OOTB
activities. You can see the label and ID. For every SOAP integration wizard, pega
creates a case with id ‘pxDataSource’. Once you complete the wizard, pega resolves
the case – Resolved-Completed.

Step 2: Click on the pxDataSource ID row which was created by you.

Step 3: You can click on Undo generation to delete all the rules created by the wizard.
 P a g e | 91

Note: The wizard will not delete the rulesets created. Please make a note and manually
delete the newly created rulesets.

How to test the Connect-SOAP rule?

Step 1: Create a new test activity – GetCustomerDetails

Step 2: Add 2 steps , Page-New followed by property-set to set all the request
parameters.

Step 3: Use Connect-SOAP method and invoke the ‘GetCustomerDetails’ service.

Step 4: Trace open the rule and run the activity. Click on the step page to check the
response.

You can see the service returns the expected result 🙂

How to Error handle in Connect-SOAP rule?

There are 3 ways to error handle

a) Transition step in connector activity.

b) Using Error handler flow in connect-SOAP rule service tab
c) Using faults tab in the Connect-SOAP rule

Transition step in the connector activity.

Pre-requisites to test transition error handling

1) Add a step to set parameter ServiceExecute to ‘true’ – Success Condition.

2) Now add step 5 to set error code and error desc parameters.

First, I didn’t add any transitions in the Connect-SOAP method .

3) In the Connect-SOAP rule, update the endpoint URL from https -> http ( you can
reverse in your own choice)

Now trace open the rule and run the activity.

 P a g e | 92

 You can see activity run, throws exception and abruptly stops at step 3.
 This will cause the run time exception and stops the process. You may get the
same error screen in user portal.

You can also click on the step 3 step page to check the error handling property values.

Now Let’s handle the error in step transition.

 In the transition step, you can use StepStatusFail when rule, to check the step
status.
 If the method status fail, then we will jump to EX label step (5th step)

We have another option – On exception, jump to later step.

You must use these option, when you use Connect methods. Connect method may
result in java exception. This option can capture java exception and jump to exception
step.

Note: Always check the method status as well as java exception in transition error
handling.

 Now trace open the rule and run the activity.

You can see, we have handled the exception in step 3 and jumped to step 5.

Error handling in flow execution.

How to invoke Connect-SOAP from a flow rule?

Step 1: Copy the activity to work class and update the activity rule to Usage – Rule
Connect in security tab ( testing)

Step 2: Open any exiting flow rule in work class ( or create a new flow rule).
 P a g e | 93

Step 3: Update the flow and add an Integrator shape.

Advanced shapes -> Integrator shape

 Configure the ‘GetCustomerDetails’ activity in the Integrator shape

Step 4: Don’t remove the exception handling in activity transition step.

Step 5: Trace open the rule and run the flow.

You can see exception is handled in the transition step and the ConnectionProblem is
not executed.

Step 6: Remove the transition from the connector activity Connect-SOAP method.

Step 7: Now open the tracer and run the flow.

You can see ConnectionProblem flow gets executed from step 3.

Note: You can customize the connectionProblem to meet your business requirement.

What are the things to remember, when you configure Connect-SOAP?

 When you are using wizard, you need the WSDL file or WSDL file location as the
only pre-requisiste.
 Wizard can create all the supporting integration rules related to Connect-SOAP
integration.
 Connect-SOAP supports only XML as messaging format.
 You can also secure the SOAP connection using WS-Security.

I will end the post here 🙂

Catch you guys in my next post 🙂

P a g e | 94