Property-Ref method
Use this method to establish links that identify a partner non-reference property for one or more reference properties.
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
GrouporListproperty) 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
GrouporListproperty 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 | 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
You can use an expression that resolves to the reference. However, you can't use
the |
| 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 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 For Page Mode Properties Choose a property of mode 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$ReferenceInformation2. 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();