Auditing rule and data changes

Your application can supplement the default information that the Pega 7 Platform maintains in the history of certain data classes or rule types, identifying which fields a user changed and the current value of the fields.

Benefits

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 PDN articles:

• How to audit field-level changes to security rule and data instances
• 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.

How security auditing works

When enabled, each save operation on a rule instance or data instance (whether through a form or through an activity) triggers execution of a standard activity. The activity compares the current values of the tracked properties with their previous values, and writes a history detail instance for each value added, deleted, or updated. The history detail identifies

• The property name
• The values added (if any are added)
• Changed values (the from value and the to value) (if any change)
• The deleted values (if any are deleted)

For aggregate properties:

• The history detail does not indicate changed values as it does for single value (scalar) properties. Instead, the history detail shows two entries when a value is changed: one entry about deleting the prior value and another about adding the new value.
• For nested PageList mode properties (such as pagelist(1).pagelist(1).property), only one level of nesting is supported. Nested PageGroup mode properties are not supported.

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.

How to enable

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. You can record changes to both Single Value and aggregate properties. For aggregate properties, only one level of nested Page mode structure is supported (for example, pagelist(1).pagelist(1).property).
2. Create a data transform named pyTrackSecurityChanges in the class. Examples with this name are provided as standard data transforms for tracking changes to access groups, Operator ID instances, Access of Role to Object rules, flows, case type rules, and application rules. You can save copies of these standard data transforms into your RuleSet and update the list of properties to be tracked.
3. In the data transform, specify Set actions to set the properties to be tracked. For each row:
   • Specify the property in the Target field. 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 the page structure.
   • In the Source column, 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.
4. Save the data transform.
5. Create a Declare Trigger rule named TrackSecurityChanges with the rule type or data class as the Applies To class.
6. Complete the Trigger tab. Select Saved for the Trigger when field. Select TrackSecurityChanges for the activity name, and Immediately for the Execute field.
7. Save the Declare Trigger rule; it takes effect immediately. Test the feature by changing a rule or data instance and reviewing the history.

Viewing and reporting security audit details

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 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.

Customizing memo text

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

1. In the Data Transform form, leave the Source column blank for the row that sets that property (in the Target 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.

Tracking changes to aggregate properties

For aggregate properties:

• The history detail does not indicate changed values as it does for single value (scalar) properties. Instead, the history detail shows two entries when a value is changed: one entry about deleting the prior value and another about adding the new value.

When creating a field value rule for a message for a Page List or Page Group property:

• For the field value rule's Applies To class, use the class of the embedded objects
• For the field value rule's Field Name (the second key part of the field value rule), match what is entered in the data transform for that property

For an example, examine the standard data transform Rule-Access-Role-Obj.pyTrackSecurityChanges. This data transform sets the property .pyPrivilegeList(1).pyPrivilege, which causes the system to track all additions and removals to pyPrivilegeList property. The Source field in the row for that property 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}.   

	History- base class
	How to complete the History tab of a data form Working with the rule History Detail display About Declare Trigger rules About Field Value rules

SysAdmin category

Open topic with navigation