Integration Mapping – Map structured rule in Pega

In this blog article, we will see more in detail about Map structured rule.

Let me start with a scenario, Our Pega application needs to talk with another application. Talk refers to the transfer of data between systems. Data can be in any format.  Now, the external system sends us input data in a file (customer details) and Pega application needs to create cases.

Note: Map structured rules are not restricted only with file integration. You can use it in multiple places

We saw in parse delimited example that the incoming data is uniquely identified or parsed using a delimited character like  |,% etc.

Prem,Male,India

You can see the incoming data can be uniquely identified by a delimiter , (comma)

Now, look at this example. The external system sends us the below input.

100009MIND

Can you identify the data?! Don’t try to decode or reason the data 😛

Actually, I forgot to tell you!!,  there is an additional agreement made between systems!

The external system says

Character 1-6     represents Customer ID

Character 7        represents  Gender

Character 8-10  represents  Address

I think now you can recognize the incoming data. This is what we call STRUCTURED DATA 🙂

When you know the offset, length of any grouped data, you can easily map/parse the values.

Note: In some financial organization, I’ve seen the incoming data is more structured so that only the authorized consumer can decode the structured data with right offset and length. We can call this as a kind of security 🙂

Ok, I will start with configuring simple map structured rule

What is a Map structured rule?

This is used in 2 ways

1. You can map the Pega clipboard properties to an output file.
2. You can also map one pega clipboard property to another pega property in either direction

We will see usages later.

Where can you reference a Map structured rule?

1. Using Connect-File method, you can map the pega properties to fixed structure output file

2. Using Map-Structured method, you can map and play between pega properties.

I want to explain about the two way of direction

Map From Property To Clipboard – Here you can parse the single input structured property into multiple clipboard properties

Map From Clipboard To Property – Here we map one or more clipboard properties to a single structured output property

Now you see a Map Structured rule can be used in both ways 🙂

What are the configuration points in a Map Structured rule?

Let’s start by creating a new map structured rule

Records -> Integration Mapping -> Map Structured -> Create

I am naming it as MapCustomerDetails.

This rule is pretty simple to configure. You have to concentrate on 2 blocks in the mapping tab.

Settings

Character encoding

This is used only when we want to map pega properties to structured output file. It means when you refer using Connect-File method

What is character encoding?

– It is a process of representing individual characters using an encoding system. For example ASCII character set represents all English characters using 0 through 127 numbers

– The character set in each application is based on the configuration in the application server. UTF-8 is the commonly used character set

– You have an option to select to which character set you need to map the data in the output file.

– By selecting default, you map it to the same character set as it is in your pega server.

Let’s keep it default

Justification & Default Pad Character

Both these settings are applicable only

1. When you use Map-structured method and
2. When mapping happens in the direction from more clipboard properties into a single structured property

For example, you want to form a structured request string in a Pega property, say Request

.Request = “C00001MIND”

0-6 characters specify the customer ID, 7^th character specifies Gender and 8-10 specify nationality.

In some situation, you have only 5 digit customer IDs. In that case, can you create a 10 character request?! No. It will be C0023FIND 9 characters. In this case, you can add some default padding character.

For now, I have specified Default pad character as %.

So the Request value will be C0023%FIND …. Wait it should be C0023%FIND or %C0023FIND?

You can decide this based on the justification configuration

Left – Padding will be added at the end C0023%FIND

Right – Padding will be added at the start %C0023FIND

Let’s jump to the second block

Map Format

This block is used to identify the position (Offset) and size (Length) of the individual data.

Offset – Determines the starting position of data. The first character always starts at 0.

Length – Specifies the length.

Again there can be confusion when you map multiple clipboard properties to a single structured property.

What if the value of the clipboard property is longer or shorter than the Length value specified?

1. When the actual value is longer than the specified length, say for example one customer ID is of 7 character, then it default truncates the 7^th character (Characters greater than the length specified)

2. the actual value is shorter than the specified length, Then you can use the Pad character & justification specified in the row to add padding.

If nothing specified specifically (Pad & Justification in each row), then the common configuration specified in the settings block will be applied.

Property – Enter the property value. This can be used to map the data and parse the data

In our example, I configured it as below

Offset determines the starting position.

Important note: The starting position starts with 0 and not 1

I have successfully configured the Map Structured rule.

It’s time to test the rule

How to test the map-structured method?

Step 1: Create a sample activity

Step 2: Add the Map-structured method. First, let’s test the ‘Map From Clipboard to Property’ direction. The second option.

So here we should already have some values in clipboard properties to map to a single structured property

Step 3: Add a step before and set the property values as shown below.

I have purposefully set the CustomerName to 5 character value to test the padding

Step 4: Configure the Map structured rule and the target property.

Step 5: For unit testing, I am adding a 3^rd step show-page and then save the rule.

Step 6: Run the activity to check the value.

As expected :), padding  is added at the right place

Now, let check the other direction – Map from property to clipboard.

Here we are going to parse the structured value and set it to multiple properties specified in the map structured rule

Step 1: In the activity first step, initialize the structured value .Request

I specified some additional character at the end. INDIA instead of IND

Step 2: Update the activity step 2 as below.

Step 3: Run the activity and check the results.

You can see Only 3 characters, as we specified in the map structured rule is set on the Nationality property!

To test the Connect-File method, please try to use my amateur post on Connect-File.

End of Map structured!