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 (as required by the selected action)
- A relation between the target and source (as required by the selected action)
- A source (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.
For an example that illustrates actions, see PDN article 26379 Introduction to Data Transform rules.
You can create initialized, empty properties by setting them equal to the empty string "". However, you should create such properties when the properties are required for use, as creating many empty properties that are later unused can result in leaving the unused properties on the clipboard, which can have a negative impact on performance and an increase in the amount of data stored.
Fields and Controls
Field
|
Description
|
   |
Click to add a new row.
Click to see the form with all rows visible (expanded).
Click 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:
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.Append to — 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.Apply Data Transform — Use this action to apply another (different) data transform to a clipboard page. 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  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.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.Exit For Each — 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 — 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.For Each Page In — 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.Otherwise — 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 actionsOtherwise When — 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 actionsRemove — Deletes the target and any associated values from the clipboard. See Remove action.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.Sort — 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 to specify the properties on which to sort and the sorting order for each property. See Sort 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.When — 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.
|
| Target
|
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  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.
When the Action is set to Sort, is displayed in the Target column, and you can click it to specify which of the Page List's embedded properties on which to sort, and the sorting order for each property.
|
| 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:
When the Action is set to Append to or Append and Map to and the Relation is set to each page in, 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
|
Specify the source of the selected Action.
The gray text in the Source field provides guidance for the appropriate type to enter. Click 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  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.
|
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 cursor on the blue dot to the left of the row's Action field. The cursor 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 cursor 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 cursor.
— Indicates the row will be inserted as a child row at the current location if you release the cursor. If you release the cursor 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? checkbox 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  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 checkbox is selected, at runtime:
- PRPC 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? checkbox 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
Data Transform form