lookup JavaServer Page tag — lookup

Use the lookup tag to retrieve and display:

  • Case 1: A property value of an instance that is stored in the database but is not present on the clipboard. (When the instance is already on the clipboard, use the reference tag.)
  • Case 2: A localized version of a property value using field value rules.

The syntax allowed for these two options differs, so they are explained separately below.

Case 1: Displaying a property value not on the clipboard

The lookup tag does not require the object that contains the value to be present on the clipboard.

To display a property value for an object without opening the object, first determine the following:

  • The name of the property for which you seek the value
  • The class that contains the instance that contains the property
  • The property or properties that identify the key parts for that class
  • The key parts of the specific instance

Here is an example, explained in detail below.

<pega:lookup className="Rule-Obj-HTML" property="pxCreateOperator">
	<pega:key name="pyClassName" value="Work-" />
	<pega:key name="pyStreamName" value="Newbook" />
</pega:lookup>

The pega:key tags are embedded in the body of the pega:lookup tag. The pega:key tag specifies the name for each key part of the instance.

To learn which properties form the key of any concrete class, review the Basics tab of a Class form. If the KEYS array is empty, review the Basics tab of the parent class rule or the associated class group data instance.

Attributes of the lookup tag

The property and className attributes are required.

Attribute Value
property Name of the property (second key part)
className Class of the property ( Applies To key part)
formatOutput Optional. Set formatOutput="true" to apply the control rule referenced on the property form when presenting the value.

Omit this attribute or set formatOutput="false" to present the property value as plain text.

This attribute is not available when the lookup tag is used to retrieve a field value rule.
mode Optional. Values are normal, literal, or javascript, or a JSP expression that evaluates to one of these three values. If no mode is specified, the default is normal

mode=normal

Use mode=normal to cause HTML encoding of specific characters when found in the input. The normal mode is the default when the mode attribute is omitted; this mode is useful in HTML-based correspondence and lookups of field value rules, which can contain these characters. Five characters are encoded:
Character Encoded Output
& &amp;
> >
< *lt;
double quote "
single quote &#039;

mode=literal

Use mode="literal" to prevent any HTML encoding. The special characters listed in the table above are passed through unchanged during stream processing.

mode=javascript

Setting mode=javascript is useful when the result of the <pega:reference > is to become part of a JavaScript script. Presents the property value in read-only mode, with certain characters within the property value escaped to a backslash equivalent. No control is applied.

Six characters are escaped:
Character Encoded Output
backspace \b
tab \t
formfeed \f
double quote \"
single quote \'
backslash \\
useCache Optional. For database lookups, the retrieved value is ordinarily retained in a temporary clipboard page, similar to the approach used for linked properties. (Such pages are deleted upon the next Commit operation in the Thread.)

This caching improves performance, by eliminating a database fetch operation if the same value is needed a little later. However, it can result in the display of stale data, or the use of stale data in a calculation or decision.

You can use either of two approaches to prevent this caching:

  • Per tag — Add the attribute and value " useCase=false " in the lookup tag System-wide — Create a dynamic system setting named prconfig/cache/EnableForlookup and set the value to "false". (Equivalently, you can use a prconfig.xml setting cache/EnableForlookup.)

Attributes of the key tag

Include a key tag that identifies a value for each key part. The name attributes is required. Either the value or ref attribute is required.

To learn which properties form the key of any concrete class, review the Basics tab of a Class form. If the KEYS array is empty, review the Basics tab of the parent class rule.

Attribute Value
name Property that forms part of the key.
value Value of that key part.
ref Expression that computes the value of that key part.

Examples:

  • <pega:key name=”KeyProperty” ref=”.SomeValue” />
  • <pega:key name=”KeyProperty” ref=”Param.SomeParameter” />
  • <pega:key name=”KeyProperty” ref=”$save(Something)” />

Case 1 example: database lookup

To display the Add Operator field for an HTML rule instance named Work-.Newbook without opening the instance to the clipboard:

  1. Determine the property that corresponds to the Add Operator field. The property that holds the Add Operator field is pxCreateOperator. To discover this, review any HTML rule, and then click the Rule Data toolbar button on the toolbar. Scan the XML display to locate the property.
  2. Determine the rule type of the HTML rule. The rule type is Rule-Obj-HTML.
  3. Determine the properties that hold the key parts for any HTML rule. You can find the key parts of any class by reviewing the Rule-Obj-Class rule instance that defines that class. The key parts are pyClassName and pyStreamName.
  4. Determine the values for the key parts for this specific instance. The value of the first key part is Work-; the value for the second key part is Newbook.

The result:

<pega:lookup className="Rule-Obj-HTML" property="pxCreateOperator" >
<pega:key name="pyClassName" value="Work-" />
<pega:key name="pyStreamName" value="Newbook" />
</pega:lookup>

The lookup tag can be used within other tags, to supply values used as HTML attribute values and in XML tags.

If the property Table Type is not None and the Use for display (not validation)? check box is selected, the output is translated according to the table contents. This can provide one approach to localization of the value.

Case 2: Displaying a localized property value

Using information in the General tab and field value rules for a property, you can use the lookup tag to convert a Single Value property text value from English (or another base language) to a locale-specific value.

To construct the localized values:

  1. Select Field Value as the Table Type on the General tab of the property.
  2. Enter the Applies To key part of the property as the Class value.
  3. Enter the Property Name key part of the property as the Field Name value.
  4. Create localization rulesets for each supported language and a version for each. For example, if the application ruleset is named ALPHA, create a ruleset named ALPHA_fr_FR to hold the French version of selected rules. Create a version 01-01-01 for ALPHA_fr_FR and add it to your access group or application rule.
  5. Sign on after you have acquired the ability to add rules to the localization rulesets.
  6. Create a single field value rule in each localization ruleset. Enter the language-specific value in the Localized Label field.
  7. Select the Use only for display (not validation)? check box. Save the Property form.
  8. In stream rules that display the property value, use the second form of the lookup JSP tag:
Attribute Value
property Reference to a property, in the context of the current stream rule.
value Optional. English value of the field, if a known constant value.
formatOutput Optional. Set formatOutput ="true" to apply the control rule referenced on the Property form when presenting the value.

Omit this attribute or set formatOutput="false" to present the property value as plain text.

mode Optional. Values are normal, literal, or javascript, or a JSP expression that evaluates to one of these three values. If no mode is specified, the default is normal

mode=normal

Use mode=normal to cause HTML encoding of specific characters when found in the input. The normal mode is the default when the mode attribute is omitted; this mode is useful in HTML-based correspondence and lookups of field value rules, which can contain these characters. Five characters are encoded:
Character Encoded Output
& &amp;
> >
< *lt;
double quote "
single quote &#039;

mode=literal

Use mode="literal" to prevent any HTML encoding. The special characters listed in the table above are passed through unchanged during stream processing.

mode=javascript

Note: Setting mode=javascript is useful when the result of the <pega:reference > is to become part of a JavaScript script. Presents the property value in read-only mode, with certain characters within the property value escaped to a backslash equivalent. No control is applied. Six characters are escaped:
Character Encoded Output
backspace \b
tab \t
formfeed \f
double quote \"
single quote \'
backslash \\

During stream processing, the system uses the user's locale to access the localization ruleset. The output is the contents of the Localized Label field.

Errors

The text "No data available" appears when:

  • The value of the value attribute is not valid.
  • The value attribute is omitted but the property value is null.
  • The value attribute is omitted but Table Type area of the General tab of the property does not support field value configuration.

Case 2 examples: localized values

Example 1

The General tab of the standard property @baseclass.pyCaption indicates that values are defined by field value rules:

pyCaption

Hundreds of standard field value rule define text values for the property pyCaption. The field value rule @baseclass.pyCaption.City in the Pega-ProCom ruleset contains an English text value "City"; the same value in the language-specific ruleset ALPHA_FR (for French-speaking locales) can have a Localized Label of "Ville". The JSP tag is: 

<pega:lookup property=".pyCaption" value="City" />

Example 2

An application contains a property Order.BoxColor in ruleset ALPHA. In the English base application, values of this property are "red", "yellow", "magenta", and so on.

To support Italian-speaking application users, the developers add a localization ruleset named ALPHA_it_IT. To support French-speaking users, another localization ruleset named ALPHA_it_FR is created.

Two sets of field value rules are created, one for each color value in each ruleset. For example, each ruleset can contain rules with these key parts:

Order.BoxColor.red
Order.BoxColor.yellow

and so on. The Localized Label of the first field value rule contains rosso for the ALPHA_it_IT ruleset and rouge for the ALPHA_fr_FR ruleset.

The JSP tag is:

<pega:lookup property=".BoxColor" formatOutput="false" />

For users working with a locale setting of it_IT, stream processing produces "rosso" when Order.BoxColor is red. Users with a locale setting of fr_FR see "rouge."

Dynamic system setting for performance and behavior

The optional dynamic system setting prconfig/useUdfToRetrievePropertyValue/database can improve performance of the lookup JSP tag when the target property is not an exposed database column in the PegaRULES database.

  • If true, database User Defined Functions are called to extract the property value from the BLOB or Storage Stream column. Only the property value is returned from the database.
  • If false, the BLOB column is returned from the database and analyzed by the server software to extract the needed property value, a more expensive approach.
Note: By default, the value of this dynamic system setting is false. As a best practice, define this setting and set it to "true".

When this setting is true, property values retrieved by the lookup JSP tag are saved temporarily on a special clipboard page, visible in the Linked Properties page grouping of the Clipboard tool. Such pages are deleted upon the next Commit operation by the requestor Thread; this reduces the likelihood of stale values.

JavaServer Page tags