Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Data transforms

Updated on January 14, 2022

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.

The two main types of data transforms are the standard data transform and the JSON data transform. When you want to convert data formats, use the standard data transform to manage your application data within internal Pega Platform applications. When you need to integrate disparate data , for example, web-based data with information provided by internal sources, use the JSON data transform.

For more information about configuring a data transform, see the following topics:

Data transforms are useful in the following situations:

  • When using data pages to manage application data (see the Where referenced section below).
  • In activities (see the Access section below).

You can create a data transform for either a clipboard or JSON model format. You select the type of data transform in the Additional configuration options section on the Create Data Transform form. The options are different depending on which model format you choose.

For the JSON model format, you can choose whether to automatically map all data in the JSON string, or you can map individual properties. Mapping individual properties is useful when you have a large JSON string and you only care about a couple of properties, when you want to change the JSON structure, and when the fields in the JSON have different names from the clipboard properties to which you are mapping. In addition, you can select classes to exclude.

Mapping JSON elements to multiple clipboard properties

If you map a single JSON element to multiple clipboard properties in a JSON data transform, the system sets the value from the JSON element on the last property. This behavior applies to properties that are included within the same hierarchy level.

For example, you set an Append and Map to action in your JSON data transform and configure two properties, .CardName and .CardName2. You set both properties to the "name" JSON element. If you run the JSON data transform in deserialization mode, only .CardName2 is set to "name" because it is the latter property in the set action.

Example of mapping the same JSON element to multiple properties

Conversely, you configure two properties called .CardName, and set one property to the “name” JSON element and the other property to the “name2” JSON element. If you run the JSON data transform in serialization mode, the system sets the value of .CardName to “name2” because “name2” is the latter field in the set action.

Example of mapping different JSON elements to the same property

Where referenced

The following data transforms that are used for data management use data pages:

  • Optional data mapping on the property form – On the Edit Property form, the Optional Data Mapping field appears when you select Copy data from a data page. Use this data transform to copy a subset of the data from the data page to the property. If you do not specify a data transform, the system copies all of the data from the data page to the property.
  • Request data transform – When a data source for a data page is a connector (an integration with an external data service), the request data transform lets you map Pega Platform data to the fields that the connector needs to communicate with the data service. Select the data transform to use in the Request Data Transform field on the Data Page rule form on the Definition tab, in the Data sources section.
  • Response data transform – Response data transforms normalize data provided by the data sources into the common application data model. A response data transform is required when the data source class is incompatible with the data page class (the recommended pattern to achieve true data virtualization). Select the data transform to use in the Response Data Transform field on the Data Page rule form on the Definition tab, in the Data sources section.

Other parts of Pega Platform that reference data transforms include:

  • Several activity methods that operate on pages can use a data transform, such as the Apply-DataTransform, Apply-Model (deprecated), Page-New, Page-Copy, and Page-Change-Class methods.
  • Starter flows, flows that create work items, can specify a data transform (on the flow's Process tab) for a Work- class to set initial properties for the work item.
  • The Action tab for a flow action can specify that the system apply a data transform before or after displaying the flow action user interface to the user.
  • For flows that have been edited by using the Flow form, data transforms can be specified on the Set Properties tab of the Connector Properties panel.
  • In various user interface elements, which include the Client Event Editor's:
    • Refresh This Section action
    • Refresh When conditions
    • On-click control rule actions Refresh Section, Show Harness, and Open URL In Window

Data transform rules can be referenced by other data transforms.

Rule types that create clipboard pages (such as Connector rules, Service rules, and other rule types) can use data transforms.


For more information about a specific data transform action, see the following topics:

Action restrictions

The following property types have limited support in data transforms and have no support in JSON data format transforms:

  • Page Groups
  • Value Lists
  • Value Groups


Use the Application Explorer to access data transforms that apply to the work types in your application. Use the Records Explorer to list all data transforms available to you.


Data transform rules are part of the Data Model category. A data transform is an instance of the Rule-Obj-Model class.

  • Previous topic Building logic and calculating values in your application
  • Next topic Data Transforms - Completing the Create, Save As, or Specialization form

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us