|
![]() |
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.
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.Group
or List
property that
does not have the Reference Property
box on theAdvancedtab 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 — however effected — 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.
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 |
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 You can use an expression that resolves to the
reference. However, you can't use the
For Value Mode PropertiesFor properties of mode For Page Mode PropertiesChoose 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 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.
|
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.
Reference pages offer two benefits:
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.
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:
You can use the Find function on the Clipboard
tool to search through the values on a reference page.
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>
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. Open the Trace Options panel.
3. Type Reference Properties
into the
Event Type field, click Add , and 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.
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();
This method updates the pxMethodStatus property. See How to test method results using a transition.
![]() | About the Logging Level Settings tool |