WSDL Structure & its relationship with Pega rules
In this blog article, we will see about the WSDL structure and its relationship with Pega integration rules. This will open up the door for SOAP Integration.
WSDL – Web Service Definition/Description Language
Update: The concept of WSDL structure is more generic and is not Pega terms. It is commonly applicable for SOAP protocol services. 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.
SOAP Integration
– SOAP is a messaging protocol that allows communication between different systems through HTTP and XML messaging formats.
– SOAP follows some standard XML specifications.
Imagine LinkedIn application provides a SOAP service to get the profile details – GetProfile
There is an Onboarding application in Pega. We need to make use of the ‘Getprofile’ service exposed by LinkedIn to get the candidate LinkedIn profile. We are able to achieve it using Connect-SOAP 😊 But…
We need all the details like how to call the service, request, response parameters, and data structure from LinkedIn to make use of the service.
WSDL was introduced to expose all the details.
What is WSDL?
– WSDL is a XML based language.
– It helps in describing the web services.
– WSDL file comes with a extension ‘.wsdl’
– They provide a standard way for web service providers and consumers to work together.
Here LinkedIn can expose a WSDL file explaining all the resources required, to consume ‘GetProfile’ service.
What do you mean by WSDL standards?
– WSDL follow some standard definitions.
– It follows some standard structure, so that every consumers can easily understand the service details
What is the WSDL structure?
We will split a complete WSDL file and go through in parts.
It is recommended to open any Connect-SOAP rule – WSDL tab. Copy the WSDL in a notepad for comparison.
1. Definitions
This holds the complete block of WSDL file. Every wsdl file starts and ends with a Definition tag
<Definitions> wsdl contents… </Definitions
2. Services
This holds all the services exposed in the WSDL document.
We can have more than one service in a WSDL
Note: Service & Operations are different here.
For example – LinkedIn profile service can contain many operations(methods)– GetExperience, GetAddress etc.
In Pega, we create integration individually for each operation or method.
Services publish Port details.
3. Port
We all know, we need some endpoint URL to access the service.
Yeah. Port specifies the end point URL
You all specify the binding details inside Port definition
<Definitions>
<Services>
<Port> binding = “Binding name” ; SOAP: Address location = “endpoint URL” </Port>
</Services>
</Definitions>
4. Binding
You specify 4 elements inside a binding definitions.
a) Type – refers to portType
b) Binding style – It can be either rpc or document. ( We will see in detail below 🙂 )
c) Binding transport – Here you specify the standard SOAP – HTTP transport
http://schemas.xmlsoap.org/soap/http
d) Operations – you can specify the various operations(methods) used within the service.
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.
- Encoded
- 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.Use it when the request is in XML format.
a) Type ( Port type) – nslt1:ServiceType
b) Binding style – Document
c) Transport – http://schemas.xmlsoap.org/soap/http
d) Operation – CustomerService
You can see few elements inside Operations
soapAction – urn:PegaRULES:SOAP:TVSTeslaVehDataCustomerData:Services#CustomerService
- It is a SOAP specific URI
- It plays the role as a SOAP message header and helps in distinguishing various operations.
e) Use – Literal / Encoded
<input> use = “literal” </input> <output> use=”literal” </output>
You can specify the styling model here – encoded or literal.
5. Port Type
You specify 2 elements inside port type
a) Operation name – you can specify various operations available.
b) Message – You can specify the input and output message.
Operation Name – CustomerService
Here you can see the operation / method specified
Message
input message – nslt1:CustomerService
output message – nslt1:CustomerServiceResponse
Here you can specify the input and output message
6. Message
It has a single element – Part
You can see input message – CustomerService includes
Part name = “CustomerServiceRequest” and element = “nslt1:CustomerServiceRequest”
So what are those elements here ?!
7. Types
WSDL data types are based on XSD ( XML Schema: datatypes)
Various data types are supported by XSD standards.
You can see the message refers to type =”tns:CustomerServiceRequestType” (marked in red)
Type ‘CustomerServiceRequestType’ is explained within blue color.
You can see, it is a complex type. It can be compared to a page property in pega.
Inside complex type, you can see many elements of data type ‘string’. You can compare it to a single value property. (eg: customer name )
We saw all different definitions.
Definitions can be classified into two types.
- Concrete descriptions
- Abstract definitions
Concrete descriptions
The describe the port address, style and transport protocol
a) Services
b) Binding
These two definitions are not reusable components
Abstract definitions
They define the SOAP messages in platform & language independent manner.
a) Types
b) Messages
c) PortTypes
These definitions are re-usable.
What do you mean by reusable here?
– You can reuse the same operations or methods for different services
– You can reuse same messages for different operations
– You can reuse same data types in different messages.
Namespaces –
Who do we use namespaces?
The main objective is to avoid naming conflicts.
For example – If you use two web service in conjunction with each other, then there can be conflicts, if same data types are used.
Note: WSDL documents can import other WSDL documents.
For example – Customer name property is used in 2 service WSDL. When we use both in conjunction then there can be naming conflicts. So using namespaces can differentiate the data types 😊
targetNamespace – declares a name space for this service
xmlns – Default namespace of the WSDL document. http://schemas.xmlsoap.org/wsdl
xmlns:wsdl – Default namespace for WSDL file. http://schemas.xmlsoap.org/wsdl
xmlns:xsd – standard namespace definitions used for specifying SOAP specific datatypes.
xmlns:soap, xmlns:soap12, xmlns:soapenc – namespaces refer to standard SOAP protocols.
xmlns:tns – stand for this namespace
xmlns:nslt1 – nslt1 is a unique identifier refers to this service.
You can refer various elements using this ‘nslt1’ namespace.
Note: No need to worry much about namespaces. They are just used to provide some unique naming.
Where do we use WSDL in Pega?
1. When creating Connect-SOAP, we consume the WSDL file provided by the service providers.
Let me show in short. I am going to consume the same WSDL file, I used above to create Connect – SOAP integration.
I am going to use an Operation called “CustomerService”
Wizard creation steps will be explained in separate article – Create Connect-SOAP Integration.
Let’s see how WSDL elements are populated in the Connect-SOAP rule.
Step 1: Designer studio -> Integration -> Connectors -> Create SOAP Integration
Complete the Wizard.
Step 2: In the App explorer, open the class structurer, open the class structure
You can see the Connect-SOAP rule created as same Operation Name.
a) Services – You can see a Class Structure with ‘ServicesService’
This is populated from Service name in wizard
b) Port – Refers to end point URL
Step 1: Open the Connect-SOAP rule. Service tab -> Connection
Step 2: check in the WSDL file -> Ports definition
c) Binding – You can verify the document style and soapAction and method
Step 1: Open the Connect-SOAP rule.
Style and Use – Document/ Literal
SOAPaction header – ‘urn:PegaRULES:SOAP:TVSTeslaVehDataCustomerData:Services#CustomerService’
Method name – CustomerService
Step 2: Check the binding part in file.
Hope you went through the two styles – Document / RPC.
Document – complex XML message formats ( XML stream)
RPC – Simple message parameters ( You can map from clipboard).
Here we use binding style – document, so Obviously Pega creates XML rules to support mapping.
Request
Response
d) Port type, Message, Data types
– Port Type refers ‘Message’ and Message refers the respective data types.
Let’s check the data type in request and response.
Check on the Integration class in App explorer.
You can see three classes created? Why?!
You can see three complex type data types. Pega creates 3 Page properties that have these classes as page definition.
You can see the data model along with AddressList property definition.
Pega created properties based on the data types in the WSDL file.
You can clearly see, how the Connect-SOAP integration wizard maps all the details from the file to the Connect-SOAP rules 😊
So whenever you come across a Connect-SOAP rule, just go and visit the WSDL tab.
Compare the WSDL definitions with the Pega rules !!
It’s always nice to learn things that are related to Pega rules.
Just google WSDL, XSD, XML and learn all the basics 😊. You will say SOAP Integration is so easy to configure in Pega 😉
