Service SOAP – Usage and Configurations in Pega

In this blog article, we will see how a Pega application can host a SOAP web service.

I request you to go through another blog article on Service-REST where I already talked about services in general –

Update: The Concept of SOAP services remains the same across different Pega versions. The screenshots in this blog article were reused from Pega 7 version. Use this blog article to learn the concepts and you can try it out in the latest versions as well.

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 😊

WSDL Structure & its relationship with Pega rules

XML Mapping rules – XML stream

XML Mapping rules extended – Parse XML

How do we configure Service-SOAP?

Business requirement: Pega system needs to host a web service – GetCustomerDetails. Other systems 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 rules for Service SOAP

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

The big question is under which layer should we create Integration class?

If the service is more application-specific you can create it in Application Integration layer and if it more specific to Enterprise we can create it under Organization Integration layer.

Let’s say we decide to create it under Organizational Integration layer.

Tip: You can create all the Integration classes as Abstract classes and not concrete.

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

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 prerequisites for Service SOAP.

How to implement Service SOAP using wizard?

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

Step 1: Select service purpose

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

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)

Important note: As per the latest versions, Pega recommended design is not to create Integration layer every time for your services. Instead you can directly use your data layer. For example, if you just need to return the policy details, which have stored under a data type. You can skip the Integration layers and straight away create the Service-REST Primary page class as Data layer.

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

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?

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.

Click next.

Step 6: Review screen

You can see totally 4 rule instances and one data instance was created.

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.

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.

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.

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.

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.

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

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.

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 tab

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 🙂

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.

Other rules that got created with the Wizard

Request parse XML

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

Response XML stream

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

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

You can see the WSDL file created for our Service SOAP

click on the WSDL file, you will find the WSDL source.

Please go through my previous post on WSDL file

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.

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 😊