02/08/2024 16:50 | Pega Academy

Application data manipulation

5 Topics 30 mins Release 2

Data Integration Pega Platform 8.5 English

In some cases, a data reference is insufficient for your business need. Pega Platform™
provides data transforms to copy selected data from one source to another and manipulate
the data as needed.

After completing this module, you should be able to:

Identify the role of data transforms in manipulating data

Configure a data transform to copy data from one case to another
Describe a data transform use case
Indicate where a data transform occurs using the Process Modeler

Available in the following missions:

Data and Integration Foundation v1
System Architect v2

Topics

Contact Us
Data Transforms

Data transforms

The purpose of a data transform is to manipulate data in an application. Data

transforms copy or manipulate data into the form you require. Data transforms can
be used to convert data from one type to another, iterate over page lists, or page
groups and copy entire pages at a time.

Consider the checkout process of a purchasing application. The customer provides a

shipping address and is prompted to provide a billing address. The billing address
and shipping address are likely the same. It is more efficient to use a data transform
to copy the shipping address to the billing address rather than have the customer
reenter the shipping address. Further into the checkout process, the customer must
provide their full name for credit card processing. Use a data transform to copy the
first name and last name properties from the customer account into a single full
name property.

https://academy.pega.com/module/application-data-manipulation/v2/print 1/11
02/08/2024 16:50 | Pega Academy

Consider another example. An auto repair parent case has a child case that handles
providing the necessary repairs. The child case contains a menu of possible items and
services that can be provided, including unit costs. The items and services that are
provided are copied to the parent case for invoicing. Use a data transform to iterate
over the list of possible items and services and only copy those entries with a quantity
greater than zero.

Tip: When accessing information in different cases (for example, in a parent-

child case relationship), consider referencing data from the parent case
rather than copying information from the parent case to the child case.
Reference data to avoid synchronization issues if data changes on the parent

Contact Us
case.

Check your knowledge with the following interaction.

This learning is interactive and cannot be experienced offline. Please visit

https://academy.pega.com to complete.

Configuring data transform

Note: The following content, referenced from Pega

Community, is included here to help you better
achieve the module learning objectives.

https://academy.pega.com/module/application-data-manipulation/v2/print 2/11
02/08/2024 16:50 | Pega Academy

To make application development maintenance more convenient and efficient, set

property values by using data transforms. When you create a data transform, you
convert data from one format and class to another format and class.
For example, if a customer enters a shipping address on an order form, you can
configure a data transform to populate the billing address with the same details.
1. In the header of Dev Studio, click Create Data Model Data Transform .
2. In the Label field, enter a short description for your data transform.
3. Optional:
To manually set the identifier of your data transform, in the Identifier section,
click Edit.

By default, the system automatically populates this field with a read-only value
that is based on the sentence that you enter in the Identifier section. The system
ignores spaces and special characters.
4. In the Additional configuration options section, select a data model format for
your data transform:

If you want to use the Clipboard tool as your data model, select Clipboard.
If you want to use JSON as your data model, select JSON.
5. In the Context section, specify the Pega Platform ruleset context for your data
transform:

a. Select an application layer in which you want to store the record.

b. In the Apply to field, select the class to which this data transform applies.
c. In the Add to ruleset field, select the name of a ruleset to which you want to
add the record, and then, in the list, select the version number.

Contact Us
6. Optional:
To override the default work item that your application associates with this
development change, in the Work item to associate field, press the Down arrow
key, and then select a work item.

For more information about default work items, see Setting your current work
item.
7. Click Create and open.
8. On the Definition tab, configure details of the data transform, based on the
selected data model:

https://academy.pega.com/module/application-data-manipulation/v2/print 3/11
02/08/2024 16:50 | Pega Academy

Choices Actions

Configure the data transform by a. In the Action column, select an action that
using the Clipboard tool you want to perform on the data.

For more information about actions available

for the Clipboard tool, see Data transform
actions for Clipboard.
b. In the Target column, specify the target of
the selected action.
c. If available, in the Relation column, specify
the relationship between the target and the
source.

The Relation column will show available

selections based on the action selected in
step a.
d. In the Source column, specify the source of
the selected action.
e. Optional:
To add more actions in your data transform,
click Add a row, and then repeat steps 8.a
through 8.d.
f. Optional:
To chain together this data transform and
data transforms with the same name in any
of its parent classes, select the Call
superclass data transform check box.

At run time, the system first performs the

Contact Us
actions in the highest-level data transform.

Auto-map the data transform by a. Select the Auto-map all data check box.
using JSON

Note: At run time, the system

maps the JSON string to the
clipboard.

b. In the Top element structure section, select

whether the structure for your data
transform is an object or an array.
c. If your element structure is an array, in the
Pagelist Property field, select the property
to which to map the array, and then select the
JSON elements.

Configure the data transform by a. In the Top element structure section, select
using JSON whether the structure for your data
transform is an object or an array.
b If your element structure is an array in the
https://academy.pega.com/module/application-data-manipulation/v2/print 4/11
02/08/2024 16:50 | Pega Academy
b. If your element structure is an array, in the
Pagelist Property field, select the property
to which to map the array, and then select the
JSON elements.
c. In the Action column, select an action that
you want to perform on the data.

For more information about actions available

for JSON, see Data transform actions for
JSON.
d. In the Clipboard column, select the clipboard
value to use for JSON serialization or
deserialization.
e. If available, in the Relation column, specify
the relationship between the target and the
source.

The Relation column will show available

selections based on the action selected in
step a.
f. In the JSON column, enter the array, object,
or simple field name from the JSON data.
">
g. In the Empty behavior column, control the
mapping results of a JSON data transform by
selecting an empty behavior.

The configuration choices include the

following options:

Default value

Contact Us
The JSON data transform serializer
maintains the preexisting value. This
configuration supports backward
compatibility with Pega Platform that are
earlier than 8.5.
Null
Represents a null value in the JSON data
transform when the associated
ClipboardPage / ClipboardProperty exists
with an empty value,
Skip
Skips mapping in JSON when the
associated ClipboardPage /
ClipboardProperty exists with an empty
value.
h. Optional:
To add more actions to your data transform,
click Add element, and then repeat steps 8.c
through 8.g.

9. Optional:
To hide all child rows, click Collapse All.

https://academy.pega.com/module/application-data-manipulation/v2/print 5/11
02/08/2024 16:50 | Pega Academy

10. Optional:
To show all child rows, click Expand All.
11. Click Save.

Data transform actions for Clipboard

To save time while processing your cases, populate data in your application by
using data transforms. When you use data transforms, you can convert data from
one format and class to another format and class.
Data transform actions for JSON
Save time while processing your cases by providing data for your application
through data transforms. When you apply a data transform, you populate target
values with values form a source that you specify, so that you avoid providing the
same data twice.
Data transforms
A data transform defines how to convert data that is in one format and class (the
source) into data of another format and class (the target). The supported formats
are clipboard and JSON. Using a data transform instead of an activity to set
property values speeds up development and makes application maintenance
easier.
Data Transforms - Completing the Create, Save As, or Specialization form
More about Declare Trigger rules
Create Declare Trigger rules to cause an activity to run when instances of a specific
class are created, updated, or deleted in the database. This implements a form of
forward chaining.

Data transform actions for Clipboard

Contact Us
Note: The following content, referenced from Pega
Community, is included here to help you better
achieve the module learning objectives.

To save time while processing your cases, populate data in your application by using
data transforms. When you use data transforms, you can convert data from one
format and class to another format and class.

When you configure a data transform using the Clipboard data model, you select an
action that you want to perform on the data. You can select the following actions:
Set
Sets the target to equal the source. You can set single-value properties, top-level pages,
embedded pages, page lists, and page groups. You typically use this action to initialize
properties. If the target pages that you specify do not exist on the clipboard, the Set action
creates the pages.

Remove
Deletes the target and any associated values from the clipboard.

https://academy.pega.com/module/application-data-manipulation/v2/print 6/11
02/08/2024 16:50 | Pega Academy

Update Page
Sets the context for setting properties on the target page. Use to set properties on a page
that is different from the primary page. If the target page does not already exist on the
clipboard, the system creates the page. If the source page is different from the primary
page, from the Relation list, select with values from, and then specify the source page.

Apply Data Transform

Applies another data transform to a clipboard page that the previous action specifies in the
current context.

Sort
Creates custom ordered lists. You can sort a page list according to single-value properties in
that page list. You can specify a sorting order for each property as either ascending or
descending order. In the Target column, click the View Sorting Properties icon to specify the
properties on which to sort and the sorting order for each property.

Comment
Specifies descriptive text. Use this action to provide comments within the sequence. For
example, you can explain the goal of a branch of steps.

When
Specifies a condition to evaluate to determine whether to apply the subsequent actions. If
the condition evaluates to true, the system applies the action within the child rows. If the
condition evaluates to false, the system continues with the action specified within the next
row. If the action in the next row is Otherwise or Otherwise When, the system applies the
action if the condition evaluates to true.
Otherwise When
Specifies another condition to meet before the system applies an alternate condition. If the
condition evaluates to true, the system applies actions within the child rows. If the
condition evaluates to false, the system continues with the action specified within the next
row. You can use this action after you use a When or Otherwise When action.

Contact Us
Otherwise
Specifies the alternate actions to apply if the preceding When or Otherwise When action
evaluates to false. You can only use this action after a When or Otherwise When action.

Note: If you add When, Otherwise When, and Otherwise actions to your data
transform, the system performs only one of these actions, depending on the first
of these actions that evaluate to true.

Append to
Copies a page to the target. You can copy a page if the source and the target are of the
same class, or if one of the classes is higher in the class hierarchy in the inheritance path.
Append and Map to
Adds a page to the target and maps properties and their source values to the target
properties. The source and target can be of different classes.

For Each Page In

Iteratively applies actions specified in the subsequent rows to all the pages in the specified
target. Ensure that the target is a Page List or a Page Group.

Exit For Each

https://academy.pega.com/module/application-data-manipulation/v2/print 7/11
02/08/2024 16:50 | Pega Academy

Exits the current iteration defined by the preceding For Each Page action. You can use this
action only as a child row of a For Each Page In action.
Exit Data Transform
Stops the data transform at the row that contains the Exit Data Transform action.

Standard Data Transforms

Data transform actions for JSON
Save time while processing your cases by providing data for your application
through data transforms. When you apply a data transform, you populate target
values with values form a source that you specify, so that you avoid providing the
same data twice.

Referencing properties

Note: The following content, referenced from Pega

Community, is included here to help you better
achieve the module learning objectives.

Provide the data necessary to process your cases by referencing information in the
form of properties. When you refer to a property, your application calls a specific
piece of information, such as a customer phone number or an address.

You can reference value properties that are strings of data such as text, number, or
dates. You can also reference page properties that contain multiple value properties.
For example, a page property .Customer might include value properties .Name,
.Address, and .Phone.

Contact Us
To refer to a property, prefix the property name with a period.

For example: To reference an order date, enter .OrderDate.

To refer to a Single Value property, enter the property name.

For example: To reference a shipping date, enter .ShippingDate.

To refer to an entry in a Value Group property, enter the Value Group name, and
then the property name in parentheses.

https://academy.pega.com/module/application-data-manipulation/v2/print 8/11
02/08/2024 16:50 | Pega Academy

For example: To reference a mobile phone number from a Value Group

property of phone numbers, enter .Phone(Mobile).

To refer to an entry in a Value List property, enter the Value List name, and then
the index number of the entry in the list.

For example: To reference the first entry in a list of discount codes,

enter .DiscountCode(1).

Apply the same guidelines when you reference Page properties.

To refer to a Page property, enter the Page property name.

For example: To reference a page with customer contact details, enter

.ContactDetails.

To refer to an entry in a Page Group property, enter the Page Group name, and
then the entry in parentheses.

For example: To reference a work address in a page group of

Contact Us
addresses, enter .Address(Work).

To refer to a page in a Page List property, enter the Page List name, and then the
page number in parentheses.

For example: To reference the third page in the page list that contains
ordered items, enter .OrderedItems(3).

To refer to a specific property on a page, enter the page name as a prefix for the
property name.

For example: To reference a city in the work address, enter

.Address(Work).City.

https://academy.pega.com/module/application-data-manipulation/v2/print 9/11
02/08/2024 16:50 | Pega Academy

Naming conventions for properties

Creating descriptive and logical names for your properties can help you convey
essential information just by looking at the name. As a result, you speed up
development of your application, promote reuse across your application, and
avoid duplicating properties that already exist in your system.
Configuring page, page group, and page list properties
To provide complete data for your cases, define properties that store related
information in a form of a page, page group, or page list. By providing properties
of a page type, you organize data in your application in a logical way, and as a
result, improve application development and speed up case resolution.
About Flow Actions
A flow action controls how users interact with user forms to complete
assignments. After selecting one flow action, users may fill in a section of the form
to complete (perform) the assignment.
Data transforms
A data transform defines how to convert data that is in one format and class (the
source) into data of another format and class (the target). The supported formats
are clipboard and JSON. Using a data transform instead of an activity to set
property values speeds up development and makes application maintenance
easier.

Adding data transform to a process

Note: The following content, referenced from Pega

Community, is included here to help you better
achieve the module learning objectives.

Contact Us
To save time, define a place in your case where a data transform occurs by adding the
data transform to a process. You typically add a data transform between two
assignments. For example, while processing a purchase order, you can populate a
shipping address with data that a user provides as a billing address.

1. In the navigation pane of Dev Studio, click Case types, and then click the case
type that you want to open.
2. On the Workflow tab, hover over a process to which you want to apply a data
transform, and then click Configure process.
3. On the toolbar, click Open process.
4. Double-click a connector between two assignments where you want to add a data
transform.
5. In the Connector properties dialog box, in the Set properties section, select
Apply data transform.
6. In the Data transform field, press the Down arrow key, and then select the data
transform.
7. Click Submit.
https://academy.pega.com/module/application-data-manipulation/v2/print 10/11
02/08/2024 16:50 | Pega Academy

8. Click Save.

Referencing properties
Provide the data necessary to process your cases by referencing information in
the form of properties. When you refer to a property, your application calls a
specific piece of information, such as a customer phone number or an address.
Data transforms
A data transform defines how to convert data that is in one format and class (the
source) into data of another format and class (the target). The supported formats
are clipboard and JSON. Using a data transform instead of an activity to set
property values speeds up development and makes application maintenance
easier.

Contact Us

https://academy.pega.com/module/application-data-manipulation/v2/print 11/11