You are here: Reference > Rule types > Data Transforms > Data Transform form - Completing the Definitions tab

Data Transform form - Completing the Definition tab

Use the Definition tab to define, in a structured sequence, the actions to be taken on the specified data. The sequence of actions is designed as rows in an array. Each row in the sequence applies the action specified in its Action column. In general, each row specifies:

An action to be taken.
A target for the clipboard data model or a clipboard for the JSON data model (as required by the selected action).
A relation between the target and source (as required by the selected action).
A source for the clipboard data model or JSON for the JSON data model (as required by the selected action).

At runtime, the system applies the specified actions according to the order in the array on this tab. A Source reference in one row can refer to a Target that is computed in a higher row.

You can create initialized, empty properties by setting them equal to the empty string "". However, creating empty properties that are not used can result in the unused properties staying on the clipboard, which can have a negative impact on performance and increase the amount of data stored.

JSON data model format fields and controls

The following fields are displayed when JSON is the data model format.

Field	Description
Auto-map all data	When selected, all data in the JSON string is mapped to the clipboard. When not selected, the grid is displayed so that you can add the properties to map.
Top element structure	Select the top element structure of the JSON that you are mapping, either object or array.
Pagelist Property	Select the Pagelist property to which to map the array.
Elements of this JSON are	Select the type of elements in the JSON. The options are objects, scalars, or arrays.

Clipboard and JSON data model format fields and controls

The following fields and controls are displayed when the data model format is clipboard and when the data model format is JSON and Auto-map all data is not selected.

Field	Description
	Click the Add a row icon to add a new row. Click Expand All to see the form with all rows visible (expanded). Click Collapse All to see only the top-level rows (nested rows collapsed). When you add a row and specify an action that requires certain subsequent (children) actions, the system automatically refreshes the display and adds rows for the required children. When you remove an action that has required children (either by deleting the row or changing the action to another one), the system alerts you that the child rows will be removed.
Action	Select the action. The JSON data model type only supports Set, Auto-map, Update page, Append and map to, Apply data transform, and Comment 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. Set is typically used to initialize properties. When target pages are specified that do not yet exist on the clipboard, the Set action creates the pages. See Set action. Auto-map - Available only for the JSON data model format. Automatically maps the JSON data to the clipboard. Remove — Available only for the clipboard data model format. Deletes the target and any associated values from the clipboard. See Remove action. Update Page — Sets the context for setting properties on the target page. Use when you want to set properties on a page that is different than 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 than the primary page, select the with values from choice from the Relation drop-down list, and specify the source page. See Update Page action. Apply Data Transform — Use this action to apply another (different) data transform to a clipboard page. JSON data model format transforms can only call other JSON data model format transforms. The Apply Data Transform action applies the other data transform to whatever page is identified by the current context. The current context is set by a preceding action (such as an Update Page or For Each Page In). Click the View Data Transform Parameters icon to specify whether to pass the current parameter page or to provide values for any input parameters for the specified data transform. See Apply Data Transform action. Sort — Available only for the clipboard data model format. Use this action to create 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. Click the View Sorting Properties icon to specify the properties on which to sort and the sorting order for each property. See Sort action. Comment — Specifies descriptive text (the comment). Use this action to provide comments within the sequence. For example, to explain the goal of a particular branch of steps. When — Available only for the clipboard data model format. Specifies a condition to evaluate to determine whether to apply the subsequent actions. If the condition evaluates to true, the actions in the following (children) rows are applied. If the condition evaluates to false, the system continues with the next specified Otherwise or Otherwise When action. See When, Otherwise, and Otherwise When actions. Otherwise When — Available only for the clipboard data model format. This action is an alternative to the Otherwise action. Use this action to additionally specify another condition to be met before applying the alternate actions. Like the Otherwise action, this action is applicable following a preceding When action. See When, Otherwise, and Otherwise When actions. Otherwise — Available only for the clipboard data model format. Applicable following a preceding When action. Use this action to specify the alternate actions to apply if the preceding When action evaluates to false. See When, Otherwise, and Otherwise When actions. Append to — Available only for the clipboard data model format. Use this action to copy a page to the target. The source and target must be of the same or compatible classes. (A compatible class is one that is higher up in the class hierarchy of the class's inheritance path. For example, class A-B is a compatible class of class A-B-C. For the Append to action, you can have a page of class A-B-C as the source and a page of class A-B as the target.) See Append to action. Append and Map to — Use this action to add a page to the target and map properties and their values on the source to the target's properties. The source and target can be of different classes. See Append and Map to action. For Each Page In — Available only for the clipboard data model format. Use this action to iteratively apply actions specified in the subsequent rows to all of the pages in the specified target. The target must be a Page List or a Page Group. See For Each Page In and Exit For Each actions. Exit For Each — Available only for the clipboard data model format. Applicable in a row after a preceding `For Each Page In` action. Use this action to exit the current iteration defined by the preceding For Each Page action. See For Each Page In and Exit For Each actions. Exit Data Transform — Available only for the clipboard data model format. Use this action to exit this data transform at this row. The system invokes the rows on this tab sequentially. Use this action to end invocation of the actions in the data transform before reaching the following rows. The actions in rows following this action are not applied.
Target	Displayed when the data model format is clipboard. Specify the target of the selected Action. The gray text in the Target field provides guidance for the appropriate type to enter. For example, when When is selected in the Action field, the Target field displays `[condition]` to indicate a when condition should be specified: Click the Open icon to open the target's rule form. Some actions do not involve targets (for example, the Exit Data Transform action). If the action does not use a target, the Target field is not available for selection. For targets that specify properties, see How to reference properties.
Clipboard	Displayed when the data model format is JSON. Select the clipboard to use for JSON serialization or deserialization.
Relation	Specify the relationship between the target and the source. The availability of the Relation settings depends on what action is selected in that row. For example, the Comment action has no associated Relation setting, and the Set action has a fixed Relation setting of equal to. The following actions have Relation settings. See the following topics for details about each action's Relation settings: Append and Map to Append to Set Update Page For clipboard data model format transforms only, when the Action is set to Append to or Append and Map to and the Relation is set to each page in, a button is displayed in the Relation column. For these actions, click this button to set a when condition on the action, so that a page from the source (a Page List or Page Group property) is appended to the target only if the condition is true.
Source	Displayed when the data model format is clipboard. Specify the source of the selected Action. The gray text in the Source field provides guidance for the appropriate type to enter. Click the Open icon to open the source's rule form. Some actions do not involve sources (for example, the Comment action). If the action does not use a source, the Source field is not available. For actions whose sources can be values, you can specify an expression. See About Expressions. For guided assistance in entering complex expressions, click the gear icon to start the Expression Builder. If you use an expression that references a value on a page other than the one for the Applies To class of the data transform you are defining, list that page name and class on the Pages & Classes tab. To enter literal constants that represent a `Date` (as "20051215") or `DateTime` value, include double quotes to distinguish them from integer constants. Don't use "" as a value to initialize a property of type `TrueFalse`. Use "True" or "False" for true or false values respectively.
JSON	Displayed when the data model format is JSON. Enter the array, object, or simple field name as it appears in the JSON data with the following exceptions: When using the Update Page action, enter a JSON object name. When using the Append and Map to action, enter a JSON array name.

Working with the action rows

Context menu actions on rows

For data transforms that have many parent-children combinations of actions, you can use the context menu options to more easily work with the action array as you design the data transform. To open the context menu, right-click an existing row (the focus moves to that row and it becomes the selected row).

Not all menu options are available for all action rows. For example, the Add Child option is only displayed in the menu if the selected row is an action that can have children (such as the When action).

`Add Sibling Above`	Click to add an action row above the selected row. The new row is added as a sibling (at the same level) as the selected row.
`Add Sibling Below`	Click to add an action row below the selected row. The new row is added as a sibling (at the same level) as the selected row.
`Add Child`	Available in the menu if the selected row can have children. Click to add an action row as a child of the selected row. The new row is added below the last existing child of the selected row.
`Cut`	Click to cut the selected row out of the array.
`Copy`	Click to copy the selected row to another part of the array.
`Paste Above`	Select a row and then click `Paste Above` to paste (insert) a cut or copied row into the position immediately above the selected row.
`Paste`	Select a row and then click `Paste` to replace it with a cut or copied row. The pasted row replaces the selected row in the array.
`Paste Below`	Select a row and then click `Paste Below` to paste (insert) a cut or copied row into the position immediately below the selected row.
`Enable`	Select a disabled row and then click `Enable` to enable that row. Enabled rows are active in the data transform, and are invoked when the system applies the data transform. If a disabled row has disabled children rows, enabling the disabled parent row also enables the children rows. You cannot enable a child row if its parent is disabled.
`Disable`	Select an active row and then click `Disable` to disable that row and prevent it from being invoked when the system applies the data transform. Disabling rows is useful when you are designing the data transform and want to test out the impact of different action combinations. If you disable a row that has nested children, the children rows are also disabled. For example, if you have a When row, and two Set rows as children of that When row, when you disable the When row, the two children Set rows are also disabled.
`Delete`	Select a row and then click `Delete` to delete that row from the array.

Dragging and dropping rows in the array

To reorder rows within the array, you can select and drag rows using the blue dots to the left of the rows' Action fields. To drag and drop a row:

Select and hold down the pointer on the blue dot to the left of the row's Action field. The pointer changes shape.
Drag the blue dot to the destination. As you drag the dot, an indicator shape appears which indicates whether the row can be inserted into the array at the current location:.
When your pointer is over the destination, release it to drop the row at the destination. Here, the Set action to set the .FirstName property has been dragged to follow the Set action for the .LastName property.

The displayed indicators have the following meanings:

— Indicates the current location is invalid. You cannot drop the row at that location in the array.
— Indicates the row will be inserted into the array at the current location if you release the pointer.
— Indicates the row will be inserted as a child row at the current location if you release the pointer. If you release the pointer and the target destination cannot have child actions, an error appears.

When you drag a row with children, the row and its children are moved to the new location.

Super Class Data Transform

Select the Call superclass data transform? check box to chain together this data transform and data transforms with the same Name in any of its parent classes. At runtime, the system first performs the actions defined in the highest-level data transform highest.

Field

Description

Call superclass data transform?

Select to cause the system at runtime to invoke data transforms with the same Name in any of its parent classes before it invokes this data transform.

Click the Open super class data transform icon to open the data transform for the superclass. In looking up the instance at design time, standard rule resolution is used (except if the rules are circumstanced, in which case the base rule is opened).

When this check box is selected, at runtime:

The Pega Platform identifies the parent of the current class using standard rule resolution.
After identifying a parent class, the system continues to identify parents, until it reaches the highest parent.
After identifying the highest parent, the system uses rule resolution to find the data transform of the same name as the current data transform.
The data transform in the highest class is invoked first. The data transform of the same name (if any) in the second-highest class is invoked next, and so on. The current data transform is invoked last.

For example, assume a data transform named MapCustomerInfo in the class MyCo-Div-Master-MyDesign has the Call superclass data transform? check box selected. At runtime, the system examines the class rule for MyCo-Div-Master-MyDesign to locate its parent class. It then locates the next-level parent class (if MyCo-Div-Master-MyDesign has pattern inheritance enabled, the next level parent is MyCo-Div-Master-) and uses rule resolution to see if there's a data transform named MapCustomerInfo in the MyCo-Div-Master- class. If not, the system goes to the next level parent (MyCo-Div-) and uses rule resolution to locate a data transform named MapCustomerInfo. The result of the runtime rule resolution search also depends on the user's RuleSet list, versions, time-based rules, circumstances, and so on.

About Data Transforms

Open topic with navigation