More about Data Page rules
 

Building a load activity

Follow these guidelines to create an activity referenced in the Load Activity field of a data page:

1. If the value in the Page Structure field on the Definition tab is Page, set the Applies To key part of the activity to the class in the Page Class field (on the Definitionpage-new tab), or an ancestor class of that class. If the Page Structure field is List, set the Applies To key part to Code-Pega-List.
2. On the Security tab of the Activity form, select LoadDeclarativePage as the Activity Type.
3. Before it starts the activity, the system creates an empty top-level page with the correct name. (If the Page Structure field on the Definition tab is List, this top-level page has the class Code-Pega-List). This becomes the primary page of the activity. In the activity, add at least one property value to the top-level page. Do not use the Page-New or Page-Remove method for that page. (You can't use the Page-Remove method in activities of this type.)
4. The activity is otherwise unrestricted; it can read or update objects in the PegaRULES database, use a connector to an external database or external system, and so on. If, within the activity, you need to refer to the name of the top-level page, use the value of param.pyPageName.

When a load activity runs, it executes in the requestor session of the requestor that attempted to access a property on the data page. Depending on the application, a data page might load only once (the first time anyone accesses the page) and remain unchanged until the node is shut down, or might reload every few seconds in multiple requestors. If frequently executed, a resource-intensive or slow load activity may affect the performance of the requestors that access the data page.

If during execution of the load activity, any exceptions are uncaught, the exception is added to the page as a message, and is also passed up to the calling activity.

Data pages are read-only

Except to the load activity, data pages are read-only. Any attempt to modify a data page (with Property-Set, Page-Copy, Page-Clear, or other processing) produces a ReadOnlyException exception.

When pages are removed

The system removes a data page (with a scope of Node) only when the system is shut down for that node (or when the rule is deleted).

The system removes a data page for a Thread when the requestor of that Thread logs out.

The system removes any data pages with a specific name when you save a Data Page rule form that has a key (Page Name field) that matches that name.

You can't use the Page-Remove method or the Clipboard tool to delete the page.

Supporting Global Resource settings

Use a Data Page rule to hold global resource settings. These allow service rules and connector rules to be identical in multiple systems, such as a test system and a production system, while using different ports, URLs, and servers.

Performance

To assess the performance impact (in your own requestor session) of data page processing, review the Full Details display of the Performance tool. This page includes three elapsed times statistics, three counts, and three CPU time statistics:

• Elapsed time spent finding declarative page names
• Elapsed time spent loading declarative pages
• Elapsed time spent determining if a page name is declarative
• Declarative Page load activities executed (count)
• Shared Declarative pages (count)
• Shared Clipboard Size (bytes)
• CPU time spent finding declarative page names
• CPU time spent loading declarative pages
• CPU time spent determining if a page name is declarative

All times are in seconds. CPU times are available only on Windows-based servers, and only after appropriate configuration.

Alert PEGA0021 for JVM Memory

Because data pages with a Node scope occupy JVM memory, they can reduce the memory available for other processing. For example, a shared page of class Code-Pega-List may contain dozens of embedded pages each with dozens of properties.

Periodically, the master agent computes the total memory space for data pages (with a Node scope). If this total is more than 5% of total JVM memory, the master agent adds a PEGA0021 alert to the Alert log recording this fact. The acts as a warning that memory and performance may be degraded by the data pages.

You may set a higher or lower threshold for the PEGA0021 alert:

1. Add a line to the prconfig.xml file:

<env name="DeclarePages/MemoryUsagePercentLimit" value="nn" />

where nn is an integer between 1 and 20.

2. Redeploy and restart to effect the updated limit.

Note: As an alternative to the prconfig.xml file, you can use Dynamic System Settings to configure your application.
See How to create or update a prconfig setting.

See PDN article Understanding the PEGA0021 Alert.

Debugging with the Tracer

To view declarative processing (by your own requestor session) with the Tracer tool:

1. Click the icon in the Quick Launch area or type CTRL+T to start the Tracer.
2. Click the Options button to open the Options window.
3. Select the needed rulesets. Enter "Data Pages" in the Event field. Click Add.
4. Click OK to close the Options panel. Begin the operation you want to trace.

Tracer output includes a line when a load activity starts, and for each reference to a data page.

Avoid potentially confusing page names

Note: Although not prohibited, as a best practice, don't choose Declare_ or D_ as the initial portion of a page name in activities. Using a page name of this form does not create a data page; data pages are created only by Rule-Declare-Pages rules.
Through a prconfig.xml file setting, you can review or extend a list of prohibited page names. See Completing the Create New dialog.

Related information