Understanding System Settings in V5.1
Summary
Beginning in V5.1, some — but not all — of V4.2 pegarules.xml settings are moved to System Settings rules and Dynamic System Settings data instances.
Suggested Approach
In Version 4.2, the pegarules.xml file holds many preferences that can be set or changed for one node of a Process Commander installation. For Version 5.1, this file is renamed to the prconfig.xmlfile, but its purpose is the same: to hold settings which may affect one node of a cluster.
There were several limitations to this structure:
- these settings refer to variables which are shipped in the code; thus, application developers were not able to add additional settings or change the functionality of existing settings (except within the values allowed by the settings themselves)
- for an enterprise-level system with many nodes, where nodes were constantly being added and removed, the system administrator would constantly have to configure the .xml files separately on each node, and make sure functionality was consistent across the system
- for an installation in a J2EE environment, it was not possible to change any of the settings without redeploying the EAR file
In Version 5.1, the System Settings functionality allows application developers to easily change or add settings. This provides a place where system constants may be set and stored in the PegaRULES database, for all nodes to access. Beginning in Version 5.1, many - but not all - of the prconfig.xml settings are moved to the System Settings feature.
Although the System Settings functionality is similar to settings in the prconfig.xml file, this new feature does not completely replace that file. As System Settings are stored in Process Commander classes (which are in turn stored in the database), the system constants can only be accessed after the Process Commander application has been initialized, and has the information to be able to connect to the database. Therefore, this functionality cannot be used for allsystem settings; the initialization settings must still be stored in the prconfig.xml file
Implementation
There are two System Setting classes:
- System Settings - instances of Rule-Admin-System-Settings
- Dynamic System Settings - instances of Data-Admin-System-Settings
Unlike Agents (where the Agent Schedules - instances of Data-Agent-Queue - are copied from the Agent Queues - instances of Rule-Agent-Queue - at startup), these two System Settings classes are distinct and separate.
The classes hold different types of values
- Rule-Admin-System-Settings instances hold constants
- Data-Admin-System-Settings instances are typically created and set programmatically.
If there is a reason for any program to update the setting (updated based on changeable factors when the system is moved from test to production) then a Dynamic System Setting should be used. If the system needs to reference a value (like a URL), but that value will not change as a result of processing, then a Rule-Admin-System-Settings instance should be used. The application developer should carefully consider the type of functionality they wish to implement before choosing one type or another.
System Settings
System Settings (instances of Rule-Admin-System-Settings) are constants stored in rule instances.
As with other rules, the System Settings which are shipped in the standard RuleSets are locked and cannot be changed. However, as they are rules, rule resolution applies.
If they need to change a value for the System Settings, application developers can save the System Setting rule to a higher-level RuleSet in the application and change its value. When the application is run, the rule in the higher-level RuleSet will override the one in the locked PegaRULES RuleSet (as always).
Application developers can also create System Settings in the application RuleSets. These settings should be considered as constants for that application (or that part of the application); they cannot be changed programmatically (by running an activity), but only by opening the rule form and updating it.
Here is a sample System Settings rule:
The Setting Key field holds the name of the System Setting, which should be a descriptive word or phrase with no spaces. This can be a single word, as in the example above.
The forward slash character ("/") is also valid in this field, and can be used to form compound names (again, with no spaces), to help sort settings into logical groupings. For example, there are several settings which relate to the full-search index, and are labeled as such: "indexing/enabled," "indexing/hostname," "indexing/ruleenabled," etc.
The Owning RuleSet is the RuleSet which "owns" the code that asks/calls for this System Setting instance (the RuleSet where the code is stored). Although the rule must be saved into a RuleSet, the Owning RuleSet field is made part of the key to this setting to provide namespace qualification.
In the RuleSet where a setting is originally defined, the RuleSet and the OwningRuleSet will be the same. When that setting is overridden in a custom RuleSet, the OwningRuleSet remains unchanged, although the RuleSet where the setting is now saved is the name of the custom RuleSet. This prevents problems when one named setting is created in two different RuleSets.
Here's An Example
Suppose that Process Commander included a System Setting called "services/initEmail" stored in the PegaRULES RuleSet. When writing the application for Acme Co., the developer also created a System Setting called "services/initEmail" which had a different functionality, and saved it to the AcmeCo RuleSet. This is fine: although these two settings have the same name, they are stored in different RuleSets.
However, if for some reason the developer had to overwrite the PegaRULES setting "services/initEmail", they could not do so if services/initEmail already existed in the AcmeCo RuleSet. Therefore, the Owning RuleSet key is added. When originally created, the services/initEmail System Setting would have the following key:
Owning RuleSet: PegaRULES
Setting Key: services/initEmailSaved into RuleSet: PegaRULES: 05-01-01
When this rule is saved into the AcmeCo RuleSet, the keys do not change, so it is defined as follows:
Owning RuleSet: PegaRULES
Setting Key: services/initEmailSaved into RuleSet: AcmeCo: 01-01-0
Thus, the rule is differentiated from the other services/initEmail, which has the following key:
Owning RuleSet: AcmeCo
Setting Key: services/initEmailSaved into RuleSet: AcmeCo: 01-01-0
System Settings Per Production Level
The System Settings Per Production Level shows the values at each production level. There are five production levels in Process Commander:
experimental development test pre-production production
The production level is set in the Data-Admin-System instance.
The System Settings instances allow the developer to provide values for the specified System Setting for all system levels. This means that if an application developer is creating an application in a development area, and plans to move it to a QA/test area and then into production, they can provide values for this System Setting for each level, and then just move the system into each area without having to reset the rule value.
As with many rules, the History tab contains the Full Description and the Usage fields.
For the System Settings rules, the Usage field should be completed with an explanation of this Setting and what it is used for, as well as any limits or other notes.
Dynamic System Settings
The Dynamic System Settings (instances of Data-Admin-System-Settings) are not rules, so they do not use rule resolution. As instances derived from the Data- base class, it is not possible to have more than one Dynamic System Setting with the same name. Again, the Owning RuleSet key field is available, to provide an additional namespace qualifier.
The Key String field holds the name of the System Setting, and should be a descriptive word or phrase with no spaces. This can be a single word, as in the example above. The forward slash character (/) is also valid in this field, and can be used to form compound names (again, with no spaces), to help sort settings into logical groupings. For example, there are several settings which relate to the full-search index, and are labeled as such: indexing/enabled, indexing/hostname, indexing/ruleenabled, etc.
Note: As these are data instances, many are not shipped with Process Commander. Some of these instances are created programmatically by the installation process, or by other system processes.
Because they are not shipped as a standard part of an application's configuration, the Dynamic System Settings do not have the five-level structure that is available in the System Settings rules. Instead, there is only a single value.
The Dynamic System Settings are designed to be created and then set programmatically through activities.
As an example, the WorkHistoryVersion setting affects the history display for work objects. This setting is not present in Version 4.2 systems, and will also not be present when you upgrade from a Version 4.2 system to the Version 5.1 system. The V5.1 system tests for the presence of this setting; if it is set to "4.2" or if it is not present, the system assumes V4.2 data for history; if the setting is present and set to "5.1," the system assumes V5.1 data.
An upgrade utility is available to upgrade the history data from the V4.2 schema to the 5.1 schema. The last step of this utility creates the WorkHistoryVersion setting, and sets it to "5.1".
System Settings API
The Public API interface PRSystemSettings allows developers to access any System Setting and to set or create Dynamic System Settings. It contains three methods:
string get(OwningRuleSet, SettingKey)
Returns the System Setting (instance of Rule-Admin-System-Settings) value represented by the given key, or null if not found. The read is performed using Rule Resolution, allowing specific named values to be overridden in customer's RuleSets.
string getDynamic(OwningRuleSet, SettingKey)
Returns the Dynamic System Setting (instance of Data-Admin-System-Settings) value represented by the given key, or null if not found.
boolean setDynamic(OwningRuleSet, SettingKey, value)
Replaces the Dynamic System Setting (instance of Rule-Admin-System-Settings) value represented by the given key. If the Dynamic System Setting does not exist in the system, it will create it and then set the value based on the value parameter
As a reminder, adding this functionality to Process Commander will speed your ability to change or add settings and provides a place where system constants can be manipulated and stored in the database for all nodes to access. This approach brings the developer more power and ease of manageability.
Additional Resources
A full list of all the System Settings appears on the 
Configuration Settings Reference Guide. This document explains the following types of settings:
prconfig.xml- System Settings (instances of Rule-Admin-System-Settings)
- Dynamic System Settings (instances of Data-Admin-System-Settings)
There are a number of features which require System Settings. The following documents describe a specific feature and how it uses System Settings: