Press "Enter" to skip to content

XML Mapping rules extended – Parse XML



I highly recommend you to view my previous post on XML Stream rule before proceeding here!!

I hope you are clear on XML Stream rule 🙂

Let’s switch gear to learn about Parse XML rules.

From the name, you can say these rules are used in parsing the XML content.

Pega connectors – When the response message is in XML, then we can use parse rule to map the properties to clipboard

Pega services – When the incoming message is in XML, we can use parse rule to parse the incoming request to clipboard.

What is Parse-XML rule?

  • Parse XML rule helps in parsing the incoming XML message and maps to Pega clipboard properties.

Note: The rule form looks similar to XML stream rule.

How to create a new Parse XML rule?

  1. Mostly Integration wizards, help in creating Parse rules. We may need to update the existing parse rules to add new elements.
  2. In rare condition, we need to manually create new Parse XML

Step 1: Records explorer – > Integration mapping -> Parse XML rule -> Create new

What is root element here?

  • Root element, just forms the Key for the Parse XML rule. ( Same like XML type in XML stream rule)
  • You can provide any valid identifier

You can verify the root element name in Parse XML rule Key part.

Where do we reference Parse XML rules?

1) Parse XML rules are mainly used in web service rules

Connect – SOAP , dotNet, Email etc

Helps in mapping the incoming XML message to clipboard properties

2) In activity you can use Apply-Parse-XML method to parse a XML content.

How to configure Parse XML rule?

Feeling happy to see Parse XML rule looks similar to XML Stream rule 🙂

I can make this post short 😀

You can see 2 main tabs here

  1. Mapping
  2. XML

I recommend you to open any existing Parse-XML rule in your designer studio and proceed!

Mapping tab

  • This is exactly the same as XML stream rule.

  • Double click on any node to check the properties.

The only difference is, you will see group subscript.

Group subscript – 

See whenever you use Page group or value group, the node name will be the default subscript value.

We can use Group Subscript option, to override the default subscript value.

There may be situation where the incoming subscript value will be of importance. We can parse and store the value in CustomerID property 🙂

Remaining all fields are same as XML stream rule. You can see detailed explanation!

XML tab

You can see 3 blocks out there

  1. XML schema
  2. XML Validation
  3. Substitutions

XML Schema – You can specify the schema URL here.

For details, please refer XML Stream rule.

This URL can be used for validation purpose

XML Validation – You can validate the XML content before parsing and setting to clipboard.

Perform validation – You have three options here.

a) Never – Never perform validation

b) Always – always performs validation

c) When – Based on when condition you can perform validation

Why do you validate a XML message?

  • We know that XML is a structured language and confined to certain standards.
  • XSD documents helps in providing the standards.

You can validate the XML message against any XML schema XSD or DTD.

For XSD – the incoming message is validated against the XSD document specified in the schema URL

For DTD – the location of the DTD must be specified  within the XML document

Schema Type – XSD / DTD

On Error –

a) Add Page message – you can add the error on primary clipboard page. This continues processing.

b) Thows exception – Adds the error on primary page and log the message. Stops processing.


Note: In simple words, you can compare substitutions with the Class inheritance in Pega.

There are two types of substitutions

  • Type substitutions
  • Element substitutions

This is a vast topic. We will see more in detail at the end 🙂

How to update a  Parse XML rule?

You can follow the same steps in XML Stream rule 🙂

You can add both elements and attributes in the mapping tab.

Let’s test now 🙂

Scenario – I got a property holding the XML content.  I need to parse the XML element and set the values to individual clipboard properties.

I am going to use the same activity, I used for XML stream testing.

Step 1: Build an activity and set an XML content in pyNote property.

Step 2: Let’s manually create a new parse XML rule in the MappingFile class.

Step 2.1: Create a new Parse XML rule.

Step 2.2: Analyze the mapping structure – pyNote

Step 2.3: Create the root element – CustomerServiceRequest

Step 2.4: Add the Customer Element, CustomerGender under root element.

Step 2.5: Add ‘AddressList’ complex type under the root element.

Remember to select repeating , then age City & state under AddressList.

Now Parse XML is ready 🙂

Step 3:  Use a New page -ParseFile

Use Apply-Parse-XML method in the activity step with step page -ParseFile

In the last step, Show-Page : ParseFile

Step 4: Run the activity and check the page content.

You can see the values are parsed and set in the page ‘ParseFile’ 🙂

Substitution types

Let’s see the substitution type now.

Please read it carefully, this is some advanced topic 😉

Type Substitutions:

  • In my point of view, both substitution types support Inheritance.

XML language explains wide range of complex data types.

XML supports inheritance. Substitution helps in Inheritance.

Say for example, Pega needs to access the external service.

  • We send the Policy number and the response will be Policy details – It can be either Home policy details or Auto Policy details
  • The external system host the SOAP web service and published the XSD document.

The response structure is like below

<ComplexType name = “Policy” abstract =”true”> ……..</ComplexType>

<ComplexType name = “HomePolicy”>

                <Extension base = “Policy”> </Extension>


<ComplexType name = “AutoPolicy”>

                <Extension base = “Policy”> </Extension>


  • You can see the 3 complex types there in response.

HomePolicy & AutoPolicy extends the Policy type. It means Policy can be extended to HomePolicy & AutoPolicy.

The response sent by the service provider can be either HomePolicy or AutoPolicy.

This is a Type substitution sample.

How Pega help in parsing the incoming XML (substitution type) message format?

Step 1: Pega creates 3 classes

Policy – TVS-Int-PolicyDetails-Policy

HomePolicy – TVS-Int-PolicyDetails-HomePolicy 

AutoPolicy – TVS-Int-PolicyDetails-AutoPolicy

  • HomePolicy & AutoPolicy extends Policy Class by direct Inheritance.
  • you can see in the above pic, Auto policy direct Inherits from Policy lass

Step 2: Pega creates 3 Parse XML rules.

a) One main Parse XML in Policy Class

b) Two other Parse XML in HomePolicy & AutoPolicy

The two parse XML will be in same name but in different class.

1. AutoPolicy

2. Homepolicy

Now Let’s check the Main Parse XML in ‘Policy’ class

Double click on the repeating element – PolicyDetails.

Mapping tab:

Node tab:

Note the Node Namespace value is ‘Policy‘ 🙂

Now check the XML tab.

You can see 2 type substitutions are added.

So how all it works?!!

Step 1: We send a request with home Policy number

Step 2: They send an XML message with HomePolicy details. ( Policy Name & Policy number)

<ComplexType name = “Policy” abstract =”true”> ……..</ComplexType>

<ComplexType name = “HomePolicy”>

<Extension base = “Policy”> </Extension>

<Element name = “HomePolicy”/> <Element PolicyNumber = “12345”/>


<ComplexType name = “AutoPolicy”>

<Extension base = “Policy”> </Extension>


Step 3: Now our Main parse XML  will start parsing the message.

  • Since type Substitution is used, Pega goes to XML tab and get the Type substitutions.
  • It check Complex type = HomePolicy and NameSpace URI to ‘Policy’ and get the class name

Note: NameSpace URI is equal to the node name of the complex element.

So here our substituted class name is ‘TVS-Int-PolicyDetails-HomePolicy

  • Now the main parse XML substitute the class with the node element class name
  • And try to find the Parse XML rule we specified, in the substituted class

Now the class will be changed dynamically and the Apply parse rule ‘ParsePolicy’  in ‘TVS-Int-PolicyDetails-HomePolicy’ is called.

Element Substitutions:

  • XML treats element substitution is different way. Different XML structure for Element Substitutions.

But our Pega treats both substitution the same way 🙂

The Only difference is Element substitutions appear in the below block in XML tab.

The XML structure can be

<element name = “Policy” type =”ns:Policy”/>

<element name = “HomePolicy” type =”ns:Home” substitutiongroup=” ns:Policy”/>

<element name = “AutoPolicy” type =”ns:Auto” substitutiongroup=” ns:Policy”/>

Here no type substitution, only element substitution.

BUT, Pega creates 3 Classes and 3 Parse rules to support the Inheritance.(same like Type substitution)

The only difference is…..

Remaining all steps are same, and  Pega dynamically calls the Apply Parse rule in respective substituted element class.

I hope you learn something new in Parse XML rules 🙂

See everything will be handled by Wizards, but It is nice to know what is happening at the back end right 🙂

Always try to hit help option and  learn every fields.

First google and know the XML, XSD, WSDL basics.

Every fields in a rule form are for some purpose 🙂

Catch you all in my next post… See ya soon


———Sorry for not replying to many comments———- Busy Office Days 🙁 ——– I will try to reply soon ———————


  1. Gopi Gopi

    Nice and Super

    • Premkumar G Premkumar G

      Thank you so much, Gopi. 🙂

  2. Rupesh Rupesh

    Hi Prem,

    i got some good information from this post thanks for it .

    i have small confusion in the difference between type and element substitution .

    i found the differences like .

    1)we define in type colums and rows for type substitution and element colums and rows for element substitution

    2)we use the type name here to identity the correct class in type substitution and use element name to identity the correct class in element substitution.

    Please reply back with your feedback on it.

Leave a Reply

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

error: Content is protected !!