Configure Service SOAP in pega

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/

 

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

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

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.

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.

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.

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/

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

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.

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.

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

 

 

18 thoughts on “Configure Service SOAP in pega

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

    1. 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 πŸ™‚

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

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

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

    Thanks
    kumar

Leave a Reply

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