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.

Usage

The Append and Map to action is equivalent to doing an Update Page action using the <APPEND> keyword. When the system invokes the Append and Map to action, it creates a new page in the target Page List property, without creating any embedded properties in that new page. Subsequent child actions create the embedded properties on the page.

When you select the Append and Map to action, the system automatically displays a child Set action because no properties exist yet on the newly created page.

When you use a source that is a Page List or a Page Group property (using the each page in choice for the Relation), the When icon appears next to the each page in choice. Click this button to specify a when condition rule for the Append and Map to action, so that a page from the source is appended to the target only if the condition is true. For example, when your target is a Page List property of PreferredCustomers, and you want to map data from an AllCustomers source Page List property only for those customers that are "preferred" customers, click the When icon and specify a when condition rule named IsPreferred.

JSON data model format

When the data model format for a data transform is JSON, there are the following differences in behavior from the clipboard data model format:

  • The order of the steps is not guaranteed.
  • The data transform is bidirectional and can be called in either direction using the executionMode parameter. This parameter indicates whether to use JSON as the source and the clipboard as the target or use the clipboard as the source and JSON as the target.
  • There are two parameters for the JSON transform. JSON transforms cannot have custom parameters.
    • jsonData – Specifies the incoming or outgoing JSON data
    • executionMode – Specifies the direction of the transform, SERIALIZE or DESERIALIZE.
  • The Pages & Classes tab is only used to specify the class of classless properties, such as pxResults.
  • JSON data model format transforms cannot reference other top-level pages. You can only reference fields on the primary page.

In addition, the JSON field requires a JSON array name.

Example

Append and Map to pyWorkPage

Relationship settings

The following relationship settings are available when the data model format is clipboard:

  • a new page – The default. Use to create a new page in the target Page List, and subsequently create properties on that page.
  • an existing page – Use to create a new page in the target Page List, and subsequently create properties on that page that are to be mapped from a source page.
  • each page in – Use to create a new page in the target Page List, and subsequently create properties on that page that are to be mapped from a source Page List or Page Group.

The following relationship settings are available when the data model format is JSON. Select the setting that matches the structure of the JSON array.

  • An array of objects – This is the only option that translates directly to the clipboard. There are no restrictions on the number of child steps or siblings.
  • An array of scalars – In JSON, an array of scalars has the format [1,2,3,...] or ["a","b","c",...]. When you choose this option, there is exactly one child step for the Append and Map to step. You cannot add siblings or disable the step. The step is a set step and the JSON side states, "each scalar element." You can specify the clipboard field to map to.
  • An array of arrays – In JSON, an array of arrays has the format [[...],[...],...], where each element is a nameless array. When you choose this option, there is exactly one child step for the Append and Map to step. You cannot add siblings or disable the step. The child step can have either an Auto-map or Append and Map to action. The JSON side states, "each array element." You can pick a Page List for the clipboard side. If you add an Append and Map to step, the same options are available again (array of objects, array or scalars, and array of arrays), so that you can configure embedded child steps.
  • A group of pages – Select this option to configure mapping to a property that contains an unordered group of embedded pages. You can map a group of pages in either direction, from the source to the target or the reverse. When you choose this option, you can set child steps to map the data for the Append and Map to step. You can add siblings, disable the steps, and perform the full set of actions available in the Action column.

Supported features

You can use the following items in the Append and Map to action:

  • In the Target column, Page List mode properties
  • In the Source column, Page, Page List, and Page Group mode properties
  • Conditionalizing the Append and Map to action, when the source is a Page List or a Page Group (using the When icon)

Restrictions

You cannot specify a Page Group mode property as the target for the Append and Map to action. That is, you cannot append to a Page Group mode property by using this action.