Data pages store data that the system needs to populate work item properties for calculations or for other processes. Developers do not have to create, populate, or otherwise manage data page instances.

When the system references a data page, the data page either creates an instance of itself on the clipboard and loads the required data in it for the system to use, or responds to the reference with an existing instance of itself. For a general introduction to data pages, see Understanding data pages.

The system manages data pages based on a combination of settings and circumstances as outlined below. The system automatically deletes, or prunes, data pages that are no longer needed, or when the maximum number of data pages is reached.

New data pages

To create a data page, see How to create a data page.

The system creates a data page instance when the data page is referenced, or uses an existing instance, depending on the settings in the Refresh Strategy section of the Load Management tab on the rule form. See Refresh strategy for data pages.

Pruning data pages

The system removes, or prunes, data pages in several circumstances.

• Single use
• Clearing unused pages
• Data page instances for a container reaches a set limit

Set single use

You can instruct the system to delete any existing data page instances and to create a instance every time the data page is referenced. On the Load Management tab, select the Limit to a single data page check box:

When the check box is selected, each time the system references the data page, it removes any existing instance and uses submitted parameters to create a data page instance.

If the check box is not selected, the system creates an instance of the data page for each reference with unique parameter values, which can cause the number of stored instances of the data page to increase rapidly.

This option is useful for parameterized data pages. See Use parameters when referencing a data page to get the right data.

Specify clearing unused pages

You can instruct the system to removed unused data page instances by selecting the Clear pages after non-use check box on the data page rule Load Management tab. This option is selected by default:

This setting has different effects depending on the scope of the data page:

• Thread scope — No effect.
• Requestor scope — Applies to both editable and read-only data page instances. The system creates a requestor-scoped instance when any thread refers to the data page. Other threads can also reference the same data page instance. If the check box is selected, the data page instance is removed when no more threads refer to it.
• Node scope — Applies to read-only data pages. If the check box is selected, the system checks the Reload if older than fields on the Load Management tab of the data page rule:
  
  The system uses any setting in these fields. If the fields are blank, the system uses the value of the dynamic system setting DeclarePages/DefaultIdleTimeSeconds, which is set by default to 86400 seconds, or one day. You can adjust the dynamic system setting value.

The number of data page instances for a container reaches the set limit

By default, the Pega 7 Platform can maintain 1000 read-only unique instances of a data page per thread. You can change this value by editing the dynamic system setting datapages/mrucapacity.

There are different data page instance containers for the thread, requestor, and node level. Each user can have both requestor-level and thread-level data pages up to the limit established. Additionally, each node can have any number of requestors, and each requestor can have many threads. See Contrasting PRThread objects and Java threads.

For each container:

• If the number of instances of a data page reaches 60% of the established limit for thread-level or requestor-level containers, or 80% of the established limit for node-level containers, the system begins deleting older instances.
• If the number reaches the established limit, the system deletes all data page instances that were last accessed more than 10 minutes ago for that container.
• If, after that step, the number of instances of the data page still exceeds the set limit, the system tolerates an overload up to 125% of the established limit for thread-level or requestor-level containers, or 120% of the established limit for node-level containers.
• If the number exceeds that overload number, the system deletes instances (regardless of when they were last accessed) until the number of entries in the cache is below the set limit.

The data page creates instances as needed to respond to references and to replace the deleted instances.

As the count of data page instances approaches the limit, the system displays the PEGA0016 alert. See PEGA0016 alert: Cache reduced to target size.

This pruning behavior is always active. You can opt to have either or both of the first two methods active for any data page.

Forcing removal of data pages

You can also force removal of non-parameterized data page instances, without regard to the settings described above. To force removal, use one of these options:

• In Designer Studio, open the rule form.

​​
Click Clear Data Page on the Load Management tab to clear all read-only instances of the data page from the clipboard according to their scope:

• Thread-scoped pages — the system removes all instances of the data page from all threads of the current requestor.
• Requestor-scoped pages — the system removes all instances of the data page from the current requestor.
• Node-scoped pages — the system removes all instances of the data page from all nodes in the cluster.

• In an activity, use the Page-Remove step with the data page as the step page. This method deletes read-only and editable data page instances regardless of the scope, as long as the data page is accessible by the thread that runs the activity.
• Use the ExpireDeclarativePage rule utility function that takes the data page name as a parameter to delete read-only, non-parameterized data page instances:
  • For Thread-scoped data pages, the system removes data page instances from the current thread of the requestor.
  • For Requestor-scoped data pages, the system removes data page instances from the current requestor.
  • For Node-scoped data pages, the system removes data page instances from all nodes in the cluster.

Passivation

Passivation allows the state of a Java object — such as an entire Pega 7 Platform PRThread context, including the clipboard state — to be saved to a file. A later operation, known as activation, restores the object.

The Pega 7 Platform uses standard passivation in general operation, but you can also configure passivation to shared storage in highly available environments. When all or part of a requestor clipboard is idle for an extended period and available JVM memory is limited, the Pega 7 Platform automatically saves clipboard pages in a disk file on the server. This action frees JVM memory for use by active requestors. (Typically, such passivation occurs only on systems that support 50 or more simultaneous requestors.)

The system passivates editable data page instances, but discards read-only data page instances.

For more information about passivation, see Creating a custom passivation method.