lookup JavaServer Page tag — lookup

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 may 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)” />

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)? box is checked, the output is translated according to the table contents. This can provide one approach to localization of the 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. Check the Use only for display (not validation)? 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 may 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  \\

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.

Example 1

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

Hundreds of standard field value rule define text values for the property pyCaption. The field value rule @baseclass.pyCaption.City in RuleSet Pega-ProCom contains an English text value "City"; the same value in a 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 may 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."

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. As a best practice, define this setting and set it to "true", unless your system does not include the database User Defined Function feature (which was introduced with V6.2SP2).

• If true, PRPC calls database User Defined Functions 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 PRPC server software to extract the needed property value, a more expensive approach.

By default, the value of this Dynamic System Setting is false.

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. See How to create or update a prconfig setting.