More about Declare Pages rules

Follow these guidelines to create an activity referenced in the Load Activity field of a declare pages rule:

1. If the value in the Page Structure field on the Definition tab is Class, set the Applies To key part of the activity to the class in the Page Class field (on the Definition 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 declarative page. Depending on the application, a declarative pages 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 declarative 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.

For a simple example, review the standard activity PegaSample-Env.LoadResourceSettings.

The system removes a declarative 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 declarative page for a Thread when the requestor of that Thread logs out.

The system removes any declarative pages with a specific name when you save a Declare Pages 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.

To assess the performance impact (in your own requestor session) of declarative 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.

Because declarative 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 declarative pages (with a Node scope). If this total is more than 5 percent 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 declarative 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.

See Pega Developer Network article PRKB-25358 Understanding the PEGA0021 Alert.

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

1. Start the Tracer tool by selecting Run > Tracer or typing CTRL + T.
2. Click the Options button () to open the Options window.
3. Select the needed RuleSets. Enter "Declare 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 declarative page.

Although not prohibited, as a best practice, don't choose Declare_ as the initial portion of a page name in activities. Using a page name of this form does not create a declarative page; declarative 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 New dialog.