History-Add method |
Use this method to cause the system to record an audit trail of the processing of a work object 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 object. (For rules, the system saves the new instance to the fixed class History-Rule.)
History processing is automatic for work objects, rules, and most data objects.
You don't need to call this method directly to add to the history of a work object. Use these built-in facilities:
Work object 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 object has no history. If an
activity calls the History-Add method for a temporary work object, the
method returns a Good
status but nothing else occurs.
Optionally, your application can write no work object history records, or only a subset of the default history records, based on the values of a system setting rule and a decision tree rule. Proj-182 5.4 See Flow rules — Controlling the volume of work object history instances.
When you click the Save button () for 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. See How to enable security auditing for rule or data changes.
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.
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.History Model REMOVED B-17342 BERRB 7/20/06 |
|||
RuleAction |
Optional. Enter one or two words characterizing the action that you want to record in history, such as "Save" or "Copy". |
|||
Category |
R-19059 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 object 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 object. |
|||
MessageKey |
R-18928 B-15237 Optional. The meaning of this field depends on the value in the previous field.
|
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 objects, 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 object 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 object.
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.
This method updates the pxMethodStatus property. See How to test method results using a transition.
audit trail, History-base class, language-specific RuleSets, temporary work object |