Property-Ref method

This method links pairs of property references that each identifies a Page mode or Value mode property.

The left reference identifies a property (or an element of a Group or List property) that has the Reference Property box (on the Advanced tab of the Property form) selected. This is known as the reference property.
The right reference identifies a property (or an element of a Group or List property that does not have the Reference Property box on the Advanced tab of the Property form) selected. This is known as the non-reference page. (The terms source and target are ambiguous here, as either page may be read or written to.)

After this method executes, changes to the properties on either of these two property references also update the corresponding properties on the other reference.

The two references may both be within the same top-level page or may belong to different top-level pages. (If they belong to different top-level pages, both top-level pages must be on the clipboard when either is accessed.)

Ordinarily, use this method in a once-only or initialization activity. The relationships you define with this method remain in force until another Property-Ref method redefines them.

Parameters

This method accepts an array of pairs of property references. Complete at least one row. If you complete more than one row, rows are processed one by one starting at the top.

Parameter Description

PropertiesRefName

Parameter	Description
PropertiesRefName	Enter a reference to a property of mode `Single Value`, `Value List`, `Value Group,` `Page`, `Page List`, or `Page Group` that has the Reference Property box selected. For a `List` or `Group` property, include a subscript (index) to identify a specific value or page within the list or group. You can use the keywords `<append>`, `<last>`, `<prepend>`, or `<insert>` to identify the item. You can use an expression that resolves to the reference. However, you can't use the `Param` or `Local` keywords here.
PropertiesRefValue	Enter a reference to a property that is to be linked to the property in the PropertiesRefName field. For a `List` or `Group` property, include a subscript (index) to identify a specific page within the list or group. You can use the keywords `<append>`, `<last>`, `<prepend>`, or `<insert>` to identify the page. You can use an expression that resolves to the reference. However, you can't use the `Param` or `Local` keywords here. Referencing provides only one level of redirection; you can't identify a reference property in this field. For Value Mode Properties For properties of mode `Value`, `Value List`, or `Value Group`, choose a property that is of the same mode and type as the property in the PropertiesRefName field. References between properties with incompatible types generate validation errors when the reference is updated. For Page Mode Properties Choose a property of mode `Page`, `Page List`, or `Page Group` for which the class in the PageClass field (on the General tab of the Property form) is identical to or derived from the class in the PageClass field of the property in the PropertiesRefName field. In this field, you can identify a page embedded in the same top-level page as the page identified by the PropertiesRefName field, or a page embedded in a different top-level page. If you refer to a page on another top-level page, ensure that your application always has both pages on the clipboard when either of them is accessed. If the PropertiesRefValue value identifies a named page or pages as a context for the property, include these page names and classes on the Pages & Classes tab of the Activity form. You can't specify a non-reference page that is a parent page to the reference page, because doing so would result in looping or infinite redirection. Design the reference and non-reference pages carefully to avoid configurations that could result in looping or infinite redirection.

Enter a reference to a property of mode Single Value, Value List, Value Group, Page, Page List, or Page Group that has the Reference Property box selected.

For a List or Group property, include a subscript (index) to identify a specific value or page within the list or group. You can use the keywords <append>, <last>, <prepend>, or <insert> to identify the item.

You can use an expression that resolves to the reference. However, you can't use the Param or Local keywords here.

PropertiesRefValue

Enter a reference to a property that is to be linked to the property in the PropertiesRefName field. For a List or Group property, include a subscript (index) to identify a specific page within the list or group. You can use the keywords <append>, <last>, <prepend>, or <insert> to identify the page.

You can use an expression that resolves to the reference. However, you can't use the Param or Local keywords here.

Referencing provides only one level of redirection; you can't identify a reference property in this field.

For Value Mode Properties

For properties of mode Value, Value List, or Value Group, choose a property that is of the same mode and type as the property in the PropertiesRefName field. References between properties with incompatible types generate validation errors when the reference is updated.

For Page Mode Properties

Choose a property of mode Page, Page List, or Page Group for which the class in the PageClass field (on the General tab of the Property form) is identical to or derived from the class in the PageClass field of the property in the PropertiesRefName field.

In this field, you can identify a page embedded in the same top-level page as the page identified by the PropertiesRefName field, or a page embedded in a different top-level page.

If you refer to a page on another top-level page, ensure that your application always has both pages on the clipboard when either of them is accessed.

If the PropertiesRefValue value identifies a named page or pages as a context for the property, include these page names and classes on the Pages & Classes tab of the Activity form.

You can't specify a non-reference page that is a parent page to the reference page, because doing so would result in looping or infinite redirection. Design the reference and non-reference pages carefully to avoid configurations that could result in looping or infinite redirection.

Results

When executed, this method establishes an enduring relationship between the reference property and non-reference property identified in each row.

If an expression appears in a parameter, it is evaluated only once.

Rows in the array are executed in order, so if one reference property is mentioned more than once during the execution, only the last relationship is effective.

If a page identified by either field is not present on the clipboard, it is added as a blank page. (However, if a higher-level page identified as context for the PropertiesRefValue page does not exist, this method throws an exception.)

When this method completes, any accesses or property changes to a property value within either page appears to also access or change a corresponding value on the other page. This includes property changes achieved through Property-Set methods, Declare Expression rules, page messages, property messages, and other methods.

Internally, only the non-reference property is maintained; accesses and updates that identify the PropertiesRefName property are automatically redirected to the PropertiesRefValue page or value.

When you save a clipboard page that includes a reference property, only the reference definition is saved. Saving only the reference definition avoids duplication of data, but also means that the properties on the reference page are usable only when the non-reference page is also present on the clipboard.

Benefits and applications

Reference pages offer two benefits:

Replacing long, complex, and possibly tedious-to-enter property references with shorter property references.
Avoiding the memory and processing demands of maintaining duplicate copies of values or pages, whether in the same top-level structure or in distinct structures.

The first benefit is realized by developers, who can type a shorter property reference rather than a longer one.

The second benefit affects both development and runtime. When an application maintains redundant data by design, developers must ensure that changes to data are propagated as fast as practical to every copy, so that inconsistent data does not affect the outputs of the application. This can be difficult to implement and test, and can affect performance. Using a reference property ensures consistency, avoids copying, and eliminates the memory and table space required for multiple copies.

Clipboard display

On the Clipboard tool display, reference properties appear on the left panel with an annotation in square brackets like [Refers to ZZZ], where ZZZ identifies the non-reference property. For example: RefPropPage (Data-Party) [Refers to pyWorkPage.pyWorkParty(Customer)]

You can use the Find function on the Clipboard tool to search through the values on a reference page.

Show-Page results

As with a non-reference page, you can use the Show-Page method to display a reference property for debugging. The resulting XML output includes the properties on the page, with a special attribute referenceTo in the root element that identifies the non-reference property. For example, the page in this XML fragment refers to a non-reference page named Grouping.Party(John):

<Owner referenceTo=-"Grouping.Party(John)" >
	<PartyID>John</PartyID>
	<HasValidLicense>false</HasValidLicense>
	...
</Owner>

Tracer output

For performance reasons, Tracer output does not by default show changes to reference properties. You can enable Tracer output temporarily for testing:

1. Use the Logging Level Settings tool to set the logging level for the following class to INFO:

com.pega.pegarules.engine.clipboard.ClipboardPropertyImpl$ReferenceInformation

2. Start the Tracer, and click Settings to open the Tracer Settings panel.

3. In the Event Type field, type Reference Properties. Click Add, then select the Reference Properties check box that appears.

4. Begin the operation to be traced. Tracer output contains a line labeled Using reference for each change to the property.

Removing a linkage

A relationship between two properties established through the Property-Ref method lasts indefinitely, or until it is replaced by a different non-reference property through a later execution of the Property-Ref method. If required, however, you can nullify the value of a reference property (linking it to nothing) with a PublicAPI method:

ClipboardProperty.resetReferenceInformation();

Checking the method status

This method updates the pxMethodStatus property. See How to test method results using a transition.

Performance

Redirection is fast. To review the number of redirections produced by your requestor session, review the Reference Property redirections value in the Rule Execution area of the Performance tool full details display.