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?
- 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)
- 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.
- 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.
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.
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.
- XML Page
- 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 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.
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.
So totally 4 style combinations are available
- RPC Encoded –This is deprecated. Use to support legacy services
- RPC literal -Use it when the request is simple parameters (Can be directly mapped from clipboard)
- Document Encoded –Not applicable in Pega
- Document Literal –Use it when the request is in XML format.
For more info – Please go through the WSDL structure post.
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.
SOAP action URI – you can specify the SOAP action HTTP request URI
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.
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 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.
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
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 !!!
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.
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!!