History writes and case auditing in Pega

In this blog article, we will see how case history can be added for auditing purpose. We will also add auditing on field level to track the changes in any case specific  values.

Audit trail gives a good picture of the case life cycle. We can track back what happened within the case from the time of creation to the time of resolution. The entire case history can be persisted in dedicated history tables and can be audited at any time.

We can also audit any specific field.

For example – Let’s say we have an auction case type. House PropertyValue will be the key property in the case type and we may need to track the Value changes at different stages in the case type. In such a case, we can enable field-level auditing on the Auction case type and enable it for the property – PropertyValue.

Adding Case history

As a pre-requisite have a simple case type ready

Create a simple case type – Auction

Whenever you define a work layer for your application (In my example it is OLVW25-MyKnowPega-Work), Pega creates a History layer for the work layer.

So all the history of the work instances can go this class.

Note: You can also use dedicated history class for each case type.

Open the History class to check the configurations.

One of the main configurations is Keys block.

Pega defined the Object key / Case key together with pxTimeCreated as the unique key for each history instance.

pxTimeCreated comes with milliseconds time precision so having two history instances for the same case at the same millisecond timestamp is highly IMPOSSIBLE to Conflict with the Primary key insertion for history instances

On the test connectivity button, you check the database table mapping.

History class is mapped to table – pc_History_OLVW25_MyKnowPega_W

You can also verify the pega database table instances.

Since I never created any case or added history, the history table is empty.

Okay, now let us start with adding history to the case.

Step 1: Create a new auction case A-1

Step 2: View the history instances from the Audit tab.

You see 4 history instances are created for the case A-1.

1. Item creation – simple case creation history.
2. Assignment creation history
3. Flow action performing history
4. Case transition to next stage history

You can find the same 4 history instances in the history table.

Tip: pyhistorytype column gives an indicator that A is for Assignment creation and F is for flow action performing history

Now the question is how this history is getting added by default.

Let’s trace back to see where the ItemCreated history got added!

It is in the GenerateID activity.

So History-Add method is used to add history instances for the case type. We will other ways of adding history shortly.

Similarly, you will find the other history memos getting added at different OOTB activities like assignment creation, completion etc.

All the OOTB history memos can be found under the field name category – pyHistoryMemo

Now the next question is, Can we control the insertion of history instances?

Because we don’t want to flood the history table with unwanted memos.

You can control it in two ways.

1. Manage case wise history writes using decision tree.
2. Manage system wise history writes using application setting rule.

Manage case-wise history writes

For example, let’s say we need to suppress the ItemCreated history memo so that we don’t need that anymore for the Auction case type.

We can do that easily.

Step 1: Open the OOTB decision tree – FilterHistory

You can see in the rule label that you can override the decision tree to turn off the history writes.

Step 2: Save the decision tree in our Auction case type class in our application ruleset and the changes will be effective only for the auction case.

Change the return value to false.

Step 3: Save the rule and create a new Auction case A-2

Switch to the Audit tab, you can see only 3 memos this time with the Item created memo suppressed.

Manage system wise history writes

You have three level of control on system-wise.

a. WRITE_NONE = All OOTB history writes will be skipped. Custom history writes will not be affected.

b. WRITE_SOME = Uses the FilterHistory decision tree to determine the history writes per case level.

c. WRITE_ALL = All history instances will be written irrespective of decision tree overrides ( for backward compatibility)

Open the application settings rule – Filter history

Above is the default configuration, you can change the value as needed.

Tip: For the changes to take effective, you need to either restart your system or run the pega activity – resetFilterHistory

Till now we have seen how Pega writes the default history instances and how it can be suppressed.

Definitely, we will have situations to write custom history instances.

What are the inbuilt ways to add history from Pega?

1. Using activity method – History-Add
2. Using OOTB Utility – AddHistory.
3. Using Audit note in flow & connector shapes.

Let’s try testing all three options.

Step 1: Create an activity of type Utility – AddAuctionHistory

Step 2: Create a new field value – AuctionInitiated under Field name – pyHistoryMemo

Step 3: Add a history-add method and add the message key.

What are the other method parameters for the History-Add

ForOperatorID – Here you can specify the operator who writes the history instance. You can also leave it blank.

HistoryMemo – There may be situations where you want to just write history as a free text memo or from a property value. In such a case, you don’t need any field value for the memo. Instead of using Category and MessageKey parameter, you can use HistoryMemo parameter to pass free text.

Tip: Using field value message key gives us an option to reuse the field value across places.

RuleAction – This is optional to add the action performed. For example – when we restore any rule instance from an older version, pega uses this method parameter and you will see the history memo Version restore.

Step 4: Call the OOTB activity and provide the memo parameter.

You can give any free text or property value dynamically.

If you open the AddHistory activity, you will find simple History-Add method only.

Step 5: Add the utility activity in the flow rule.

So this will be executed in the case life cycle.

Step 6: Add audit note in the flow.

Utility shape supports adding audit notes.

In the same flow shape which we used in step 5, add an Audit note.

So we added 3 custom memos in 3 different ways.

Save all the rules.

Step 6: Create a new case and check the audit tab.

You see all of our 3 custom history memos are added 😀

What if we want to audit a specific field? – We want to track the property value changes.

In such use case, you can use field-level auditing.

Adding Field History

How to add field-level auditing?

Step 1: Open the case designer for Auction.

In the settings tab, you can configure the auditing.

Step 2: Enable field audit and add the PropertyValue field to the audit.

Save the case type.

Note: In the earlier versions, field level auditing is configured via the below navigation Configure -> Case Management -> Work Management -> Field Level Auditing. But this is now deprecated and can be enabled only from the case designer.

Step 3: For testing purposes add the PropertyValue field in multiple places so that we can track the change in property values.

I added the property in the assignment shapes of the first stage and second stage.

Step 4: Save and run the case.

In the first screen, I give the value as 350000

In the Property Valuation screen, the value is changed to 400000

Submit the case.

Step 5: Switch to the audit tab and field history.

You will see the value changes tracked for the field property value.

How Pega handle this field-level auditing?

1. A new declare trigger is created for the case type – pyFieldLevelAuditing

So on committed save, this declare trigger will fire and take the responsibility to add the history instance for the value changes.

2. Pega uses a new class rule and a new DB table instance to store the field auditing.

Class Name – FLAudit-OLVW25-MyKnowPega-Work-Auction

You will the 2 instances under this class.

The class is mapped to DB table instance – pc_FLAudit_OLVW25_MyKnowPega_W

Okay final question, how do we migrate the Field level auditing configuration to a higher environment?

Make sure to package the class rule instance and DB table instance.

We are at the end of this blog article.

As a summary,

1. Pega can Inbuilt perform history writes for cases by three options

– OOTB utility – AddHistory

– Activity method – History-Add

– Audit note in flow & connector shapes.

2) You can manage the history writes on case level using decision tree – FilterHistory and on system level using application settings – FilterHistory.

3) You can also audit on field level to track the value changes.