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.
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:
- Configuring a data transform
- Configuring the JSON data transforms settings column
- Unit testing a data transform
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.
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.
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 SectionactionRefresh Whenconditions-
On-click control rule actions
Refresh Section,Show Harness, andOpen 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.
Actions
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
Access
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.
Category
Data transform rules are part of the Data Model category. A data transform is an instance of the Rule-Obj-Model class.
- Data Transforms - Completing the Create, Save As, or Specialization form
- Configuring a data transform
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.
- Data Transform form - Append and Map to action
Use the Append and Map to action to append a page to the target Page List mode property and set the context to that page for subsequent child actions to map properties on that page. The target and source can be of different Applies To classes.
- Data Transform form - Append to action
- Data Transform form - Apply Data Transform action
Use the Apply Data Transform action to apply actions defined in another data transform (the applied data transform).
- Data Transform form - Auto-map action
Use the Auto-map action to contextually and automatically map data from JSON to the clipboard or from the clipboard to JSON.
- Data Transform form - For Each Page In and Exit For Each actions
- Data Transform form - Remove action
- Data Transform form - Set action
Use the Set action to set the target equal to the source. When you specify a target page that does not yet exist on the clipboard, the Set action creates the page.
- Data Transform form - Sort action
- Data Transform form - Update Page action
Use the Update Page action to set values on a target page that is different from the data transform's primary page.
- Data Transform form - When, Otherwise, and Otherwise When actions
- Configuring the JSON data transforms settings column on the Data Transform form
Pega Platform displays the Settings tab on the data transform rule form for the JSON data model format. Use the Settings tab to enable multidimensional array output and to specify fields to skip during auto-mapping. You might want to skip fields that do not have meaning outside of Pega Platform, such as pyObjClass.
- Data Transform form - Completing the Pages & Classes tab
To use page names in fields on the Definition tab, you must specify those pages on this Pages & Classes tab.
- Adding data transform to a process
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.
- Standard Data Transforms
- More about data transforms
Using a data transform, you can specify initial properties for objects of a specific class and also map properties (and their values) of an instance of a class to an instance of a different class.
- Unit testing a data transform
You can use the Run Rule feature to test a data transform individually before testing it in the context of the application that you are developing. Additionally, you can convert the test run into a Pega unit test case.
Previous topic Building logic and calculating values in your application Next topic Data Transforms - Completing the Create, Save As, or Specialization form