How to configure Service Package in Pega

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.

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

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.

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

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 

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. 

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.

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

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