Integration Mapping – Parse XML rule in Pega
In this blog article, we will understand some more new information about the XML mapping rule – Parse XML. A Final step towards SOAP Integration 😊
I would suggest you to visit the blog article on WSDL unfolding and XML stream rules –
Update: The activity rule methods remains the same across different Pega versions. 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.
Parse-XML – 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?
Parse XML rule looks similar to XML Stream rule
You can see 2 main tabs here
- Mapping
- 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 a detailed explanation!
XML tab
You can see 3 blocks out there
- XML schema
- XML Validation
- Substitutions
1. XML Schema
You can specify the schema URL here.
For details, please refer XML Stream rule.
This URL can be used for validation purpose
2. XML Validation
You can validate the XML content before parsing and setting to the 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 is confined to certain standards.
– XSD documents help 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.
3. Substitutions
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 lengthy 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.
We can use the same activity which we 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>
<ComplexType name = “AutoPolicy”>
<Extension base = “Policy”> </Extension>
</ComplexType>
– 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 does all it work?!!
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>
<ComplexType name = “AutoPolicy”>
<Extension base = “Policy”> </Extension>
</ComplexType>
Step 3: Now our Main parse XML will start parsing the message.
Since type Substitution is used, Pega goes to XML tab and gets the Type substitutions.
It checks Complex type = HomePolicy and NameSpace URI to ‘Policy’ and gets the class name
Note: NameSpace URI is equal to the node name of the complex element.
So here are substituted class name is ‘TVS-Int-PolicyDetails-HomePolicy’
Now the main parse XML substitutes 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 a 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 the same, and Pega dynamically calls the Apply Parse rule in the 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.
