Press "Enter" to skip to content

Configure Service SOAP in pega



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.

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 😊


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

Response – TVS-Int-GetCustomerDetails_Response


  • 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

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)

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

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

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 🙂

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 J

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 😊

Catch you guys in my next post!!



  1. Sushilkumar Bomane Sushilkumar Bomane

    Thank You…PremKumar!!!

    • Premkumar G Premkumar G

      You are welcome, Sushilkumar. 🙂

  2. Santosh Kumar Mohapatra Santosh Kumar Mohapatra

    Hi Premkumar G,

    Thanks for all the information & your hardwork.
    First time today I am going through your website.
    I have two question in my mind since couple of days.
    Q:- What are the Prerequisite to list down before planning for a Pega Integration?
    Q:- How to Plan Enterprise class structure by keeping Integration in mind?Which layer we should place integration ? And we should plan class structure.

    Waiting for your response.

  3. RayMir RayMir

    Awesome Explanation…Thank You Prem 🙂

    • Premkumar G Premkumar G

      Thank you and you are most welcome, RayMir. 🙂

  4. Pradeep Pradeep

    Good stuff..

    Prem. In this post, we have Address,PolicyDetails page under Response page. where this Address & PolicyDetails classes are created as per your explanation. Can you specify them here

    • Premkumar G Premkumar G

      Hi pradeep, I have created it manually. Since I am showcasing a demo, i created all the rules newly. you can also make use of any existing classes cool 🙂

  5. Jeh... Jeh...

    hello sir, I have some questions because I tried everything in your tutorial regarding this service soap but I don’t get any Parse XML. i also tried to run the service soap but I got only errors. hehe
    by the way sir this is very helpful for me. thumbs up sir! very good

  6. Shrikanth Shrikanth

    Prem, Great job brother!! Your articles are so detailed any new pega learner doesn’t need to go anywhere else but to follow your posts.

    Do you have any tutorial on Pega learning?

    • Premkumar G Premkumar G

      Thank you so much for your appreciation, Shrikanth. 😀
      I’m sorry to say that I am not having any tutorials on Pega learning.

  7. Ravi verma Ravi verma

    can you please give me brief description of Service activity rule..

    • Premkumar G Premkumar G

      Hi Ravi Verma,

      I’m thinking about making a post of it. I will post about it soon. Stay tuned. 🙂

  8. kumar kumar

    hi admin.
    this is an excellent explanation of integration rules,

    i have a query on error handling
    lets say service got Fail:internalserver error then i have to jump to some step in the activity i have tried with stepstatus fail jumptolatestep (Err) but instead of jumping it is failing in the Connect-SOAP step in the activity,
    can you please help me on this.


    • Premkumar G Premkumar G

      Hi Kumar,
      Please use On Exception, Jump to option to handle all exception in step transition 🙂

  9. Saurabh Saurabh

    your posts are fantastic … Awesome..

    • Premkumar G Premkumar G

      Thank you so much for your appreciation, Saurabh. 🙂

  10. sanal sanal

    Nice Article.

    I have a problem of Work object not getting created when hit from soap Ui client.
    The same is working fine when doing it from studio running the soap service manually.

    Could you suggest what could be wrong


  11. Prithvi Raj Prithvi Raj

    Thanks alot Prem. You are a life saver.
    Can you please make a post on report definition as well?

  12. Debarati Dey Debarati Dey

    Very informative. Thanks once again for sharing such knowledge in depth.

  13. Prasad Prasad

    Thank you Prem, It’s very helpful in configuring Service-SOAP

    • Premkumar G Premkumar G

      You are most welcome, Prasad. 🙂

  14. Muneeb Muneeb

    Hi Prem,

    Nice explaination Prem, Great Job!!
    Can you please tell me how to send the response as JSON.

  15. Anvith Anvith

    Can we add or remove request or response properties in already generated wsdl?

  16. Ajay Ajay

    Hi Prem,

    In the service activity i see the response is set with hard coded values, suppose if i want other than this then do we need to set the response properites created in pega to response page.Can you please explain


  17. Ajay Ajay

    My other question is Clipboard of XML we can use either to set the request ,so for this also in the service activity we need to set the request properties created in pega to the request,i guess i am missing some understanding here.Can you please explain.


  18. Kunal Anand Kunal Anand

    Hi Prem,

    Thank you for this awesome post . Could you please explain me the use of Connect Wait with some real time scenarios . Also why do we need to create a parallel requestor session while implementing the JMS calls ?

    Thanks a lot .

    Kunal Anand

  19. Raghu K Raghu K

    This post is awesome Prem. Where can i see the URL for this Service-SOAP??

  20. Parag Parag

    Thank you Prema.. you made our life easy with these post…..
    I have one doubt….We have created one service, now we want to get some more data in request xml from calling application and will be sending some extra data in response. I believe we need to add some properties in request and response xml. Can you please tell me the approach?

  21. Kumar Kumar

    Very Nice and helpful article!. Can you also give some more details about mtom part with an working example in pega.

  22. Surabhi Surabhi

    Hye prem thanks for explain in detail. I have couple of doubts:
    1) if I consume a service and I give the request say parameter or property like coupon I’d and I want that client should immediately get a error message right there while he’s giving input before he even clicks on submit button of soap ui then how can we do this?
    2) if we have a scenario where user consumes service and has made a workobject and is working on it and service fails. We need to rollnack everything created by user including case I’d. How can we rollback from client side?

    Thanks in advance.

  23. Shyam Shyam

    Hi Prem,

    Could you please make an post on SSO using LDAP or SMAIL.


Leave a Reply

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

error: Content is protected !!