Pega-RULES agents

The six agents in the Pega-RULES ruleset perform general system housecleaning and periodic processing:

• SystemCleaner

• SystemPulse

• SystemIndexer

• RuleUsageSnapshot

• StaticContentCleaner

• SystemWorkIndexer

SystemCleaner

By default, this agent runs the standard Code-.SystemCleaner activity once every 24 hours for housekeeping tasks, which include purging the following items:

• Older records (instances) from log tables

• Any requestors that have had no activity during at least 48 hours

• Rows from the pc_events database table according to the EventsRetentionPeriod Dynamic System Setting (the default retention period is 90 days)

• Any nodes that have not responded to the pulse for 30 days

Optionally, you can add an activity that is similar to Code-.SystemCleaner to another agent to purge outdated information and recover tablespace. Ensure that the agent has access to the needed rulesetversions, and do not purge instances that are referenced in other tables.

You can change the idle requestor purge criterion to a value that is less than 48 hours by overriding the test in the called activity System-Requestor-Context.CleanupExpired. Once per day, this activity calls Log-Usage.UsageCleaner, which trims older rows of the pr_perf_stats table (corresponding to the Log-Usage class). This activity starts a stored procedure, passing a number of days to retain based on the value of the pxProcess.pxLogUsage RetentionPeriod property. The default is 30 days, which can be updated through an entry in the prconfig.xml file or in the Dynamic System Settings.

SystemPulse

The Pega 7 Platform uses two types of system pulse processing: database pulse and cluster-based pulse.

Database pulse

When the Pega 7 Platform is configured to use database pulse processing, the activity Code-.SystemPulse is used to synchronize the contents of the in-memory rule cache on a node with rules that are stored in the PegaRULES database.

This process is set to a default interval of 60 seconds. To see the date and time of the most recent pulse on each node, in the System Management Application (SMA), select Administration > Pulse Status.

Note: To change the system from using database pulse to using cluster-based pulse, first update the value attribute for initialization/pulse/transport to "cluster" in the prconfig.xml file or the Dynamic System Settings, and then perform a complete cluster shutdown and startup.

The rows of the pr_sys_updatescache database table, which corresponds to the System-Updates-Cache class, form the input queue. Rows of this table have one of the following record types:

• CACHE — Notifies all nodes of rules created, deleted, or updated since the most recent pulse.

• INDEX — Records the need to incrementally update Elasticsearch indexes (indexes are typically created and saved only on one or more nodes of a cluster).

• DELLC — Indicates that the Lookup List Cache (LLC) was deleted on this node, signaling other nodes to delete their own LLC. Deleting this cache is a manual option in the SMA.

• RFDEL — Indicates that a static-content rule from one of the Rule-File- rule types was deleted, signaling all nodes to delete the extracted static file.

• RUF-X — Indicates that a library was regenerated on one node, signaling other nodes to regenerate this library.

To see a list of updates not yet posted by pulse processing, review the standard report System-Updates-Cache.InstanceList.All..

During pulse processing, library recompilation requested on one node is propagated and repeated on other nodes. After a developer clicks Generate Library on the Packages tab of a Library form or selects the Compile Libraries check box on the Import Archive form, the system extracts and compiles (on the developer's node) the functions in that library. At the next opportunity, system pulse processing on each other node of a multinode cluster compiles that library, keeping the compiled versions synchronized across all nodes.

Cluster-based pulse

When the Pega 7 Platform is configured to use cluster-based pulse, the system sends pulse messages directly to the other nodes. Any changes to rules are immediate and are not synchronized during the pulse operation. The SystemPulse agent is bypassed during this process, acting as a heartbeat for the system that updates the last pulse time in the database. As a result, the pr_sys_updates cache table remains empty at all times.

When cluster-based pulse is used in a multinode system, changes to the contents of the rule cache are synchronized during the pulse operation. However, any changes to a rule saved on one node are immediately reflected in processing that occurs on any other nodes.

SystemIndexer

The standard activity Code-.SystemIndexer updates the search index cache that supports the operations of the full-text search facility for rules and data instances. Typically, this activity runs every 60 seconds, so after saving a new or updated rule, the updated information might not immediately be displayed in search results.

You can enable or disable full-text index processing through the System Settings landing page. See System category — Settings page.

RuleUsageSnapshot

The standard activity Code-.RuleUsageSnapshot normally runs once every 24 hours. If the system has run for at least an hour since startup, this activity takes a snapshot of the cache, writing out instances of the Log-RuleUsage class and Log-RuleUsage-Details class.

StaticContentCleaner

The standard activity Code-.StaticContentCleaner deletes files from the server file system containing static content, such as images (JPG, PNG, or GIF file types), style sheets (CSS file type) and JavaScript files (JS file types) in the StaticContent folder. Normally, this activity runs once an hour.

In a production system, this activity deletes extracted static content from the static content directories that is older than 30 days. In a non-production system (based on a production-level setting of 1, 2, 3, or 4), the default retention period is 3 days (72 hours).

Eliminating older static content reduces the number of files and subdirectories in the server's StaticContent directory, saving disk space and improving file access. If a user with a specific rulesetlist later attempts to access a static content file that was purged, the file is re-extracted from the Rule-File-zzzz rule in the PegaRULES database on demand.

The DateTime property pxProcess.pxAdminSystem.pxLastStaticContentPruning on the Process page identifies the last time this activity started.

Note: In a production setting, items derived from rules including ruleset lists, images, CSS style sheets, and JavaScript files change infrequently. Changing the prconfig.xml file or Dynamic System Setting to a value longer than three days can improve some user response times slightly by reducing on-demand extractions.

SystemWorkIndexer

The SystemWorkIndexer agent periodically updates Elasticsearch indexes to support text-based searches for work items. Elasticsearch indexes for work items are created only when the Dynamic System Setting PegaRULES:indexwork/enabled is set to true. A check box on the Advanced tab of the Class form controls which work items are indexed.

Application users accessing the Pega 7 Platform from the User composite portal or another composite portal that incorporates the @baseclass.FindWork section can search for work items by using full-text search. You can enable or disable full-text index processing through the System Settings landing page.

Pega-ProCom agents

The agents in the Pega-ProCom ruleset process email, service-level agreements, and assignments. The agents in this rule provide the following types of processing:

• Processing service-level agreements and escalation (ServiceLevelEvents)

• Applying a flow action to assignments in bulk (AgentBulkProcessing)

• Sending out email correspondence (SendCorr)

• Checks whether starting flows references have been updated (GenerateStartingFlows)

• Checking incoming email (deprecated) (Email_CheckIncoming)

Ensure that the Pega-ProCom agents rule has access to all the RuleSet Versions it needs. Symptoms of incorrect configuration can include:

• Escalation events do not occur as expected

• Email correspondence is generated but not sent

1. Checking incoming email (deprecated)

This agent is deprecated but is available for backwards compatibility. As a best practice, configure and use email services to manage incoming.

2. Processing service-level agreements

The activity System-Queue-ServiceLevel.ProcessEvent supports service-level agreement processing for both assignments and work items. Enable this row of the Agent Schedule form unless your applications use only non-BPM rules-engine facilities.

This agent uses a queuing facility for higher throughput. Flow processing creates queue entries (instances of the System-Queue-ServiceLevel class) and the activity dequeues them and processes them.

By default, this activity starts every 30 seconds; you can choose a higher or lower interval.

You can update three standard settings rules to control how many assignments the agent processes in a batch and other parameters. See PDN article Understanding service levels and System Settings for the Pega-ProCom agent.

3. Applying a flow action to assignments in bulk

The activity Assign-.AgentBulkProcessing performs background processing of flow actions in bulk against assignments, when requested through the bulk processing feature of the Process Work workspace of the Case Manager portal. See Running flow actions in bulk .

Enable this row of the Agent Schedule form to allow managers to process assignments in the background.

Because this activity is designed to detect and work around locked work items, enable this row on only one node (of a multinode cluster) unless this causes your system to have unwanted long delays in background bulk processing. Increasing the number of simultaneously executing copies of this activity may not increase throughput in proportion, because of contention for locks.

When you start the bulk process, the system creates an instance of the Assign-Schedule-Future class, which serves to notify the Pega-ProCom agent that a bulk processing request is pending. It changes the owner of assignments to be processed to the reserved value pyBulkProcessing, so that they are no longer on the original worklist or workbasket.

As it processes assignments, the Pega-ProCom agent temporarily creates instances of the Assign-Schedule-InterimResults class. When processing is complete, it forms and sends the email message.

When background processing by the Pega-ProCom agent is complete, the agent sends an email message listing the count of assignments selected and processed, and a list of the keys of assignments not processed. On the work item history display, the phrase "system on behalf of NAME" (where NAME is an operator full name) indicates that bulk processing requested by that operator occurred in background.

4. Sending out email correspondence

The activity Data-Corr-.Send supports outgoing email if your system contains one or more Email Account data instances with a second key part of Notify.

This agent uses a queuing facility that allows the agent to run on multiple nodes without risk of locking or deadlock issues, for higher throughput.

See PDN articles How outbound email works and How to set up outbound email.

5. Processing starting flows (not used)

Not used.