How to enable security auditing for rule or data changes

For example, you can record the name of the application rule that is referenced in an access group, each time a user updates the Access Group form and adds, changes, or deletes an application rule. For another example, see these Pega Developer Network articles:

• PRKB-24127 How to audit field-level changes to security rule and data instances
• PRKB-24131 How to extend the security auditing feature to record changes to additional properties

This capability, known as security auditing, supports change auditing for sensitive fields on selected rule or data objects.

The details of each change appear on the History Details display and are summarized through several standard reports.

When enabled, each save operation on a rule instance or data instance (whether through a Form Builder form or through an activity) triggers execution of a standard activity. The activity compares the current value of specific properties you have listed to be tracked with the previous values, and writes a history detail instance for each value added, deleted, or updated. The history detail identifies the property name, added value, changed values (from and to), or deleted value. (For aggregate properties, one history detail instance is created for each changed value.)

For rule changes, the system saves this information as an instance of the History-Rule class. For changes to data instances, the information is saved in an instance of a subclass of the History-Data- class. For example, the system records changes to access groups (Data-Admin-Operator-AccessGroup) in instances of the History-Data-Admin-Operator-AccessGroup class.

Complete these steps for each data class or rule type that is to support security auditing. Place these two rules in a RuleSet that is available to the users to be audited.

1. Identify the set of properties to be recorded. (The RuleData toolbar buttonmay help you identify property names.) You can record changes to both Single Value and aggregate properties.
2. Create a model rule named pyTrackSecurityChanges in the class. Four examples with this name are provided as standard model rules for tracking changes to access groups, Operator ID instances, Access of Role to Object rules, and application rules. You can save these model rules into your RuleSet and update the list of properties to be tracked.
3. In the Property column of the Model form, list the properties to be tracked. For Value List or Value Group properties, enter an arbitrary subscript to identify one value. For Page mode properties, enter a reference to a scalar property within any page. (The subscripts and embedded property names are necessary to save the Model form. They do not restrain which elements of aggregate properties are tracked by this feature.)
4. In the Value column of the model form, optionally enter a word or phrase to label, on the History Details report, the value. For example, if the property is named pyUserName, enter the phrase "user name" to generate text "Changed user name from John Smith to Jon Smyth". Alternatively, leave the Value column blank for a row to apply custom text from a field value rule, described below as an advanced feature.
5. Save the model rule.
6. Create a Declare Trigger rule named TrackSecurityChanges with the rule type or data class as the Applies To class.
7. Complete the Trigger tab. Select Saved for the Trigger when field. Select TrackSecurityChanges for the activity name, and Immediately for the Execute field.
8. Save the Declare Trigger rule; it takes effect immediately. Test the feature by changing a rule or data instance and reviewing the history.

From the History tab of a rule or data form, click  History Details   to see the detailed memo text created by this instance.

For a broader view of changes, run the standard list view rules:

• History-Rule.TrackSecurityChanges for changes to rules
• History-Data-Admin-Operator-ID.TrackSecurity for changes to data objects of any class. The Applies To value of this list view rule does not restrict the class of the results.

Enter from and to values for a date range to restrict the results of these reports.

You can create custom reports or export this data. The pyLabel property identifies the property modified. The pyMemo property contains the text description of the change.

Using field value rules, you can customize or localize the memo text presented on the History Details reports for a property:

1. On the Model form, leave the Value column blank for the row that contains the property in the Name column.
2. Create three field value rules. Set the first key part to the rule type or data class and the second key part to the property name.
3. Set the final key parts to the three values TrackSecurityChange_Add, TrackSecurityChange_Change, or TrackSecurityChange_Remove.
4. On the Localized Label tab, enter the text to appear in the memo field.  In the TrackSecurityChange_Add  field value, you can use {1} to refer to the new value of the tracked property. For the TrackSecurityChange_Change field value, {1) to refer to the old value and {2) to refer to the new value. For the TrackSecurityChange_Remove  field value, you can use {1} to refer to the old value of the tracked property.

For example, to provide custom text for changes to the property pyDefaultAppName on the access group form, the Localized Label text:

Updated the application from {1} to {2}.

At run-time, this produces a memo similar to:

Updated the application from Mortgage to ConsumerLoan.

For aggregate properties, users cannot change a value, they can only add and remove values.  When creating a field value rule for a message for a Page List or Page Group property, use the class of the embedded objects as the Applies To class; for the property (second key part), match what is entered in the model rule.

For an example, examine the standard model rule Rule-Access-Role-Obj.pyTrackSecurityChanges. This model rule references the property .pyPrivilegeList(1).pyPrivilege, which causes the system to track all additions and removals to pyPrivilegeList property. The Value in the model is blank, which causes the system to retrieve field value rules for the memo text. Because pyPrivilegeList is a Page List property with a PageClass of Embed-Access-Privilege, the field value rule that tracks when a privilege is added is named:

Embed-Access-Privilege.pyPrivilege.TrackSecurityChange_Add

The Localized Label of that field value rule refers to properties for a single privilege instance:

Added privilege {.pyPrivilege} level {.pyPrivilegeLevel}.