Press "Enter" to skip to content

XML Mapping rules – XML stream



In this post, we will see some new information about the XML mapping rules.

Hope you guys liked my previous post on WSDL Unfolding.

If you have missed, Please checkout the link below.

In this post let’s move one more step closer to SOAP Integration πŸ™‚

  • We know that SOAP supports XML messaging formats.

It means, say if you want to communicate with other systems through SOAP protocol, you need to send the message in XML format.

Similarly, If Pega hosts a SOAP service, then other system needs to send the message in XML format.

  • So, Now tell me how message is processed within Pega application.

Properties. Yes properties help in storing data.

We know different modes of Pega properties

Single value, value list/group, Page, Page list/group etc.

So we have the data as properties, who will be converting the data to XML format?

XML Mapping rules πŸ™‚

What are the XML mapping rules?

  • In Pega, we got 2 XML mapping rules.

XML Stream – Maps the clipboard data to outgoing XML formats

Parse XML – Parse the incoming XML to clipboard data.

First we will see XML Stream rule.

How to create a new XML Stream rule?

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

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

Step 2: Enter the identifier and XML Type

What is XML Type?

  • This forms a Key to the XML stream name.
  • You can assign some valid name here.

Note: You can use MapFrom XML Type when you need to use this XML stream in Pega service response.

Where do you refer XML mapping rules?

  1. XML mapping rules are mainly used in web service rules

Connect – SOAP , dotNet, Email etc

  1. In activity you can use 2 methods to use XML mapping rules.

a) Property-set-XML – refer XML stream

b) Apply-Parse-XML – referΒ  Parse XML rule

How to configure XML rules?

  • Mostly the Connect/Service wizard , helps in creating XML mapping rules.

Let’s straightaway go to through the XML stream rule

I already created a sample XML stream πŸ™‚

I will suggest you to open any existing simple XML stream.

We will walk through each fields

There are 2 main tabs.

  1. Mapping
  2. XML

Purposefully first I am going to explain the XML tab πŸ™‚

XML tab

You have 2 blocks,

1) XML schema

Schema URL – You can specify the URL of the XML Schema document here.

This is applicable only for Auto-generated XML.

What do you mean by schema URL?!

  • XML Schema provides documentation on the available elements and attributes.
  • XML Schema can be available in either XSD or DTD documents.

Just click on the below URL to see a Sample XSD Schema URL

This Schema URL can be external or it can refer to the ServiceExport directory in web servers.

You can see the above URL referring to service export directory


2) XML generation

Auto-generated XML – Maximum use this option, toΒ  Auto generate XML.

  • It means the XML source is auto-populated based on the configuration in the mapping tab.
  • If you uncheck this option, then mapping tab content will be disabled. (Like the same as Non- auto generated HTML section)

Use SOAP 1.1 encoding

  • You can use this option to add the attributes referring the element data types.

Let me show you.

a) This is XML source with encoding

You can see the xsi:type attribute added to the elements.

b) XML source without encoding

You won’t find the data type attributes.

Remember, encoding will help people let you know the data type for each element. So what do you say. Use Encoding πŸ™‚

  • This is applicable only when Auto-generated XML is checked.

Add type attribute to root element –

  • This is applicable only when SOAP 1.1 encoding is unchecked.
  • Use this option to add the data type attributes only to the root element ( parent node)

You can see the xsi:type attribute added to the root element alone πŸ™‚

Omit extra spaces – Always check it. This will eliminate the extra spaces without altering the content.

Generate forΒ  – JSP

XML source – When Auto generated, this will be altered based on the configuration in mapping tab.

When non-auto generated, you need to manually update the XML content for this XML stream rule.

Mapping tab

  • Helps in mapping Pega properties to XML structure.

Allow tree editing?

  • Only one selecting this, we can manually add the attribute or element or delete those elements.

If you uncheck Allow tree editing

You can see Add element, Add attribute and Delete buttons are missing πŸ™‚

What is the difference between attributes and elements?

First, the XML message format is not only limited to SOAP. It can be extended to Email, file also.

Check out the below example

Sample 1:

<CustomerServiceRequest CustomerType=”Platinum”>

<Name> Prem </Name>

<Age> 26 <Age>


Sample 2:



<Name> Prem </Name>

<Age> 26 <Age>


In sample 1, we added Customer type as attribute and in sample 2, we added customer type as element.

So now tell me, what is attribute?

  • Attributes, can be used to refer the data characteristics.

Note: There is no such restriction like we should use only attributes or elements in any situation.

But prefer elements over attributes, when you refer any data.

  • In HTML, we normally use these attributes to define the styling characteristics like Bold, background color etc, but In XML maximum we use individual data ( prefer element).

Whenever, you host a SOAP service, Pega creates only elements and no attribute will be Added.

When you consume any external service(Connect), then attributes are possible.

The main differences are

  1. Attributes can contain only single value, while the element can be extended to hierarchical structures.
  2. Similarly we can extend the elements and add new elements inside (like page property, adding new single value property inside a page), but we cannot extend attributes.

Note: You can see elements are identified by β€˜e’ and attributes by β€˜a’

Element properties

Step 1: Just double click on the CustomerServiceRequest element.

Node Name – This is just a label name.

Node TypeΒ  – Attribute / Element

You can specify the node as either attribute or element.

Below you have 3 tabs.

Mapping tab

Mapping Mode –

You got 3 options to choose from – Standard, Literal XML or Apply rule

What are these 3 options?

a) Standard – When this option is selected, Pega constructs the XML message based on this node and its child node.

This will be default selected.

b) Literal XML – When this option selected, Pega constructs the XML message based on the XML content from source property (mapping tab)

c) Apply rule – When this option is selected, Pega constructs the XML message from the other referred XML stream rule. It’s like calling another XML stream rule.

a) Standard Mapping Mode

We have 3 fields to configure for standard mapping mode.

Context Page – If the element refers to Page / Page list property, you can refer the property in this field.

In our case, it is page property – CustomerServiceRequest, which hold the customer details.

Context Class – This will be pre-populated based on the Context page property.

Source property – You will this, when the element refers to any single value property.

Open the CustomerAge element and check the mapping tab.

You can see, for CustomerAge single value property, Context page is null & Source property holds the single value property.

Note: Context class here, refers to the Parent context page class.

Let’s check the XML table – XML source (auto generated content)

Here XML source is generated based on the nodes available in the mapping tab.

b) Literal XML mode

  • Here Source property is mandatory. You need to specify the Source property, from which the XML content can be copied.

Let’s check the XML source page.

You can see the XML content is copied from the source property.

c) Apply Rule mode

Here you can specify another XML stream rule, from which we can build the XML message

Stream Name – Specify the new XML stream rule name to refer

XML Type – enter the second keyword to XML stream name.

It’s like calling another XML stream rule. Let’s check the XML source page.

Node tab

In node tab, you have 5 configuration points.

Node Namespace – This is just a identifier. You can add a namespace prefix to the element. In case you have same time of element, this will serve as a unique identifier.

It is not a mandatory option. Cool πŸ™‚

Optional –

Imagine when CustomerAge property is null for certain cases. So here in the XML stream, we can configure the element to behave Optional. It means,

  • If the element is null, then it will not be added to the XML stream message.
  • If not checked, the message will always contain empty element tags with no values.

NillableΒ  – This is related to Optional field and applicable only when Optional is not selected.

So when optional is not selected and the clipboard data is null, then we can send a special attribute within the element β€œxsi:nil”.

  • Select Nillable option and check the XML source page

Substitution group – It can be None/ type/ element.

This is a vast topic in XML πŸ™

We will see in detail in Parse XML rule πŸ™‚

Type tab

You have 5 configuration points here.

XSD Base TypeΒ  – This is applicable when we use SOAP encoding 1.1

We know SOAP encoding specifies the data type. Here in this field, you can specify the Data type of each element.

Note: When the type is simple like decimal, Integer, then you can directly refer the name here ( for single value property). When the type is complex ( page type property) then you can specify β€˜anyType’

Check for the page property, Β XSD base Type is anyType

Type Name – This is applicable when we use SOAP encoding 1.1

You can specify any valid name here. This name will be used in referring to data types.

Check the XML page.

  • You can see the Type name for CustomerserviceRequest page. ( You see ns1 – name space)

Similarly for CustomerName element, we didn’t add any Type name so default value β€œxsd” used.

Type Namespace – This is applicable when we use SOAP encoding 1.1

You can specify the namespace value here ( unique identifier)

Default value – You can also have an option to specify a default value for the element.

  • For customer age, I added default value to be 26.

Now check the XML page – you must see the JSP directives with when condition.

Is SOAP Array – This is applicable when we use SOAP encoding 1.1

When selected, the element should contain immediate child as a repeating element.


These are all just some understanding about the XML stream rule :). Maximum we will not create a new XML stream, but we may update it.

How to update a XML stream rule?

a) Add a new element

Say you need to add Gender under CustomerServiceRequest.

Step 1: Select the node to which you need to add an element.

Step 2: Click on Add element button.

Step 3: Double click on the node and open the properties.

Step 4: You can update the node and type tab.

Step 5: Save and check in the XML tab.

You can see Gender added to the XML source πŸ™‚

Now CustomerGender property in Pega, can be send in the XML message request.

b) Add a new attribute

I need to add a attribute Salutation to CustomerName

Step 1: Select the CustomerName element.

Step 2: Click on Add attribute button.

Step 3: double click on the new node and add the salutation property.

In attribute node, all Mapping, node & type tab more or less resemble the element node.

Step 4: Save and check in the XML tab.

You can see the salutation attribute added πŸ™‚

How to use the XML stream in Activity method?

Step 1: Create a test activity – TestMappingXML

Step 2: Populate the request page with all required values.

MappingFile.CustomerServiceRequest will contain all the details.

Step 3: Use Property-Set-XML method to set the XML content to pyNote page.

I am going to use the same XML stream, I used before.

Let me open it again for you.

Step 4: Use a show-page for testing πŸ™‚

Step 5: Run the activity and check the page.

You can see the pyNote is populated with XML content with all values we provided πŸ™‚


I will end the post here :). I hope you got some good information on XML stream rules.

Follow through my next post on Parse XML rules……………………………………………………………………..

XML Mapping rules extended – Parse XML

  1. Raju Raju

    What a beauty
    Lovely material on pega

    First on internet no one till now have explained this much clearly and that too for free wow amazing

    I Would have hugged you if you are by the side in happiness

    Thanks a lot

    • Premkumar G Premkumar G

      I’m feeling very elated on reading your comments, Raju. πŸ™‚
      Thank you so much, Raju, πŸ™‚
      You are most welcome. πŸ™‚

  2. Narasimha Narasimha

    Your doing amazing help for Pega developers and for Learners.
    Thanks for your lot of support. Can you please explain about File Listener and MQ Listener’s in coming episodes. Please


    • Premkumar G Premkumar G

      Feeling very glad on reading your comments, Narasimha. Thank you.
      You are welcome. Yeah, I’ll explain about those soon. πŸ™‚
      Stay tuned. πŸ™‚

  3. Das Das

    Hi Prem,

    I have query regarding how to send UserName and Password in my request header how to achieve this.

    Please let me know.

    • Premkumar G Premkumar G

      Hi Das, that is simple. for connectors, we will be sending the request.
      if the external system hosts a webservice, they must have defined some parameters for username and password in the header fields.
      So all you need to do is map the operatorID – user name and password to some parameter value.
      Pass those parameters in the connector rule header fields.

  4. pra pra

    Hi Prem,

    i have doubt like.. what is ServiceExport directory? how do we find it in our proj? and one more que like using this xml file can we import it and create a work object?

    thanks in advance

  5. pra pra

    HI prem,

    another query.. how can we upload file to service export directory?
    is it similiar to local host?

    pls answer..thanks

  6. Prashanthi Prashanthi

    Awesome explanation.
    Thanks alot for explaining in detail.

    • Premkumar G Premkumar G

      Thank you so much, Prashanthi. πŸ™‚
      You are most welcome. πŸ™‚

  7. saumya saumya

    The explanation is great.
    However I have a query, when we go for mapping Mode as Literal XML and Apply Rule.
    Any real time example?

  8. Ravikiran Ravikiran

    Thank you Prem for your extended help.

    • Premkumar G Premkumar G

      You are welcome, Ravikiran. πŸ™‚

  9. Lakshmi Lakshmi

    Hi Prem,

    I have question regarding mapping of XML response to Clipboard. How can we do this?
    I have tried Apply-Parse-XML, but where the parsed results will store?
    Kindly provide solution.
    Thanks In Advance!

  10. garima garima

    Hi Permkumar g ,

    I studied All your post , they all are amazing. Also recommended my friend circle about Your site. Seriously not having words to thank you.

    You r doing gr8 job πŸ™‚

  11. Harshita Sharma Harshita Sharma

    Hi Prem,

    Thank you for the beautiful explanation. I have a query – Can you please explain more about XML type with an example or something more detailed?

    That will be very helpful.

    Thanks in advance! πŸ™‚

  12. Navneet Agarwal Navneet Agarwal

    Awesome Prem. Love reading your posts

Leave a Reply

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

error: Content is protected !!