WSDL Structure & its relationship with Pega rules

Introduction

WSDL – Web Service Definition/Description Language

In this post we will see about the WSDL structure and its relationship with Pega integration rules.

This will open up the door for SOAP Integration.

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, 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?

I am going to split a complete WSDL file and explain you in parts 🙂

I recommend you 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.

  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.

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.

  1. Concrete descriptions
  2. 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 lesson 😊 – 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 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 😉

Soon I will come up with SOAP Integration rules !!

14 thoughts on “WSDL Structure & its relationship with Pega rules

    1. Hi Sruthi,
      normally in pega, whenever an exception or an alert occurs, system throws a log message. This log message is mainly used for debugging purpose.
      Manually we can insert a log message through an activity method : Log-Message.
      The method expects ‘message’ and ‘logging level’ as parameter.
      Message – you can specify message rule or hard-coded string value.
      Logging level – you can specify the available logging levels – Debug, info, warn, error.
      There is a special logging level – InfoForced. When you set this logging level, log message is always logged and is independent of the log level settings.

  1. Hi Prem ,

    I appreciate your passion and effort and all the topics which you have covered am going through , these posts are boosting my knowledge in pega and i have posted some request comments waiting for reply. Thanks

    1. Hi Pradeep,

      I’m so sorry for replying very late. Since I was on the verge of finishing my project at that time. I’m feeling happy to hear that you like all my posts. Don’t worry bro, I’ll reply to all of your doubts as soon as possible. 🙂

      You are welcome. 🙂

    1. Hi Sumit,
      Glad to hear that you are finding my blog useful. Yeah, many people have asked for these topics, I’ll post about them soon. Stay tuned. 🙂

  2. Hi Prem,

    Firstly Thanks for sharing PEGA knowledge. You are doing an awesome job. The level of explanation and examples u r providing are terrific. My favorite is RULE availability :).

    I know u r going to post on all debugging tools but mentioning so that it may get priority in ur list.

    Thanks again for all ur hard work.

    1. Hello Vivek,

      You are most welcome. Thank you so much for your heartfelt motivating comment. I’m glad to hear about your favorite. I’ll try to post about your favorite as soon as possible. Stay tuned. 🙂

      Thank you so much for your heartfelt appreciation and you are welcome. 🙂

  3. Premkumar,

    Thanks for the article. I am facing an issue in Connect SOAP in my project. I imported the WSDL and all the rules get created. The application is able to generate the required request XML but we are getting “Transport Level information does not match with SOAP message namespace URI”. Where do you think the problem is? Is it Pega mapping or the service interface’s WSDL?

Leave a Reply

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