Data Transform form - Completing the Definitions 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 that is 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 run time, 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.

Note: 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 effect on performance and increase the amount of data stored.

JSON data model format fields and controls

When JSON is the data model format, the following fields are displayed.

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 the 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

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

Field Description
  To add a new row, click the Add a row icon.

To see the form with all rows visible (expanded), click Expand All.

To see only the top-level rows (nested rows collapsed), click Collapse All.

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 supports only the 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 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. 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 Update Page or For Each Page In ). To specify whether to pass the current parameter page or to provide values for any input parameters for the specified data transform, click the View Data Transform Parameters icon. 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 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 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 that a when condition should be specified.

To open the target's rule form, click the Open icon.

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.

For details about each action's Relation settings, see the following topics:

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, to set a when condition on the action, click this button. If the condition is true, this appends a page from the source (a Page List or Page Group property) to the target.

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. To open the source's rule form, click the Open icon.

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 quotation marks to distinguish them from integer constants.

Do not 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 is displayed 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.

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.

Not all menu options are available for all action rows. For example, the Add Child option is displayed in the menu only 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 from 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 the effect 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, select and drag rows.
  1. Select and hold down the pointer on the blue dot to the left of the row's Action field. The pointer changes shape.
  2. Drag the blue dot to the destination. As you drag the dot, an indicator displays whether the row can be inserted into the array at the current location.
  3. When your pointer is over the destination, release it to drop the row at the destination.

The displayed indicators have the following meanings:

  • Invalid destination — Indicates that the current location is invalid and you cannot drop the row at that location in the array.
  • Insert row — Indicates that the row will be inserted into the array at the current location if you release the pointer.
  • Insert row as parent — Indicates that 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 is displayed.

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 run time, the system first performs the actions that are defined in the highest-level data transform.

Field Description
Call superclass data transform? Select to cause the system at run time to invoke data transforms with the same name in any of its parent classes before it invokes this data transform.

To open the data transform for the superclass, click the Open super class data transform icon. 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 run time:

  1. Pega Platform identifies the parent of the current class by using standard rule resolution.
  2. After identifying a parent class, the system continues to identify parents, until it reaches the highest parent.
  3. After identifying the highest parent, the system uses rule resolution to find the data transform of the same name as the current data transform.
  4. 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.
Note: If any of the invoked data transforms fail, an error is returned.

For example, assume that 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 a data transform named MapCustomerInfo is 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 run-time rule resolution search also depends on the user's ruleset list, versions, time-based rules, circumstances, and so on.