History-Add method

History classes are created automatically in many cases:

  • Work objects — Instances of concrete classes derived from History-Work- class are created when a work item advanced through a flow, typically through the Work-.AddHistory activity. Others are added automatically. History are visible on the work history report, typically accessed from the History tab on the user form. See the Pega Community article How to control history instances written to the audit trail.
  • Rules — Instances of the concrete History-Rule class are created when you create a rule (with Save or Save As after New) when you save a rule into a ruleset not requiring check-out, and when you check in a rule into a ruleset that requires check-out. These are visible from the History tab of the rule form. The history instance for a checked-in rule contains the entire previous contents of the rule before update.
  • Data — Instances of concrete classes derived from the History-Data- class are created when a form (such as the Operator ID form) is saved or when a Data Table row is saved.
    Note: Data tables are now superseded by local data storage.

In other situations where history is needed, your application can include an activity that calls the History-Add method. Use this method to cause the system to record an audit trail of the processing of a work item by users (or other requestors). Each use of the method appends a new instance to similar instances belonging to a concrete class derived from the History- base class. Typically, these record important events and changes in the course of the object.

History details are "append only." The system saves the new instance to the class History-ClassGroup of the underlying work item. (For rules, the system saves the new instance to the fixed class History-Rule.)

History processing is automatic for work items, rules, and most data objects.

Work item history

Use these built-in facilities to add to the history of a work item:

  • When updating a flow rule enter text into the Audit Note field in the shape properties panel. The Audit Note field is available for several flow shapes, including connector flow actions (arrows), Decision shapes, Subprocess shapes, and End shapes. During flow execution, the Pega Platform records the date, time, current operator, and text as the shape is processed. Your Audit Note text can include reference JSP tags, to record the value of specific properties.
  • If your application needs to record history instances at points in the flow beyond those in existing, add into the flow a Utility shape that references the standard activity Work-.AddHistory.
  • Your application activities can call the Work-.AddHistory activity as often as needed to extend the information kept as history.

Work item history instances are added to the concrete class named History-Zzzzz, where Zzzzz is the name of the class corresponding to a class group (work pool).

A temporary work item has no history. If an activity calls the History-Add method for a temporary work item, the method returns a Good status but nothing else occurs.

Disabling or limiting work item history

Optionally, your application can write no work item history records, or only a subset of the default history records, based on the values of an application setting rule and a decision tree.

See Managing case history.

History for rules and data instances

When you save a rule or data form, the system creates a history instance. In addition, the system creates a history instance to record rule check-in.

You can modify the text that is added for such events.

Other cases

Your application can record history for an object in additional situations. In such situations, use the History-Add method. History instances promote accountability and save supporting detail. They are not used for database rollback or transaction back out.

Parameters

This method has five parameters:

Parameter Description
ForOperatorID

Enter an Operator ID value (literal or property reference) to be recorded in history. Typically, enter pxRequestor.pyUserIdentifier to record the current user.

HistoryMemo Optional. Enter a property or literal string that becomes memo text. Leave this blank if the memo text will be provided by a field value rule.
RuleAction Optional. Enter one or two words characterizing the action that you want to record in history, such as "Save" or "Copy".

To capture instance history for Rule-, Data-, and Link- instances, set RuleAction to one of the following values:

  • Save
  • Delete
  • Version Restore
Category Optional. Identify a localization category to be used when the system displays this history memo and the output will be localized based on field value rules in a language-specific ruleset. The default is pyHistoryMemo, corresponding to the property Work-.pyHistoryMemo. which applies to work item history

Leave blank if no category is appropriate, if you prefer alternate text to that produced by the standard field value rules, or when this method adds to the history of an object that is not a work item.
MessageKey Optional. The meaning of this field depends on the value in the previous field.
  • pyHistoryMemo — If you choose pyHistoryMemo in the HistoryMemo field, select the third key part of a field value rule which has Work- as the first key part and pyHistoryMemo as the second key part. As a foundation, your system includes a few dozen standard field values supporting common work item processing. For example, the standard field value rule with key Work-.pyHistoryMemo.FileAttached produces on the history display (in English) the text: 
    A file has been attached {1}.

    where {1} is replaced by the file name.

    This approach supports localization of the work item history display.

  • Another field value — If you selected an application-specific value in the HistoryMemo field, enter the third key part of a field value rule for which pyHistoryMemo is the second key part. The first key part is a class related to the current primary page.
  • blank — If you left the HistoryMemo field blank, enter the key of a Rule-Message rule. If the text of that message rule contains parameters, follow the key with " \t" and the value to be substituted for parameter {1}, then "\t" and the value to be substituted for parameter {2}, and so on.

Results

The system creates and saves a history instance in the concrete class derived from the History- base class that is associated with the class of the object.

For rules and work items, history is maintained automatically. For example, when you save a rule form, an instance is added to the History-Rule class. When you update a SimpleTask work item in the PegaSample sample application, an instance is added to the History-PegaSample-SimpleTask class. Your application can add to history at other points in the progress of a work item.

The new history instance is saved but not committed. Make sure that your activity or a later activity always performs a Commit method to make this new data instance a permanent part of the database. (This occurs in flow executions automatically when the flow ends, or when the next assignment is created.)

Each history instance contains a date, type, user ID, and memo. If you supply the values in the HistoryMemo parameter, the history instance can contain additional properties, such as the "before" values of certain properties. For example, you can create a history instance that indicates: 

Credit limit increased to $12,000 from $10,500.

Similarly, if dates, parties, addresses, or other important facts are modified, the text can record the previous value and the new value. Of course, your processing must retain the old value in a property, parameter, or local variable at least temporarily.

Checking the method status

This method updates the pxMethodStatus property.

See How to test method results using a transition.