Real Time Usage of "HistoryWalker" API. Difference between Audit & History

[Narsing1]

Brief Description 

Recently I came across one of the community post that made me exited to look deeper into it and try to see all the possible use cases in real time with regards to "HistoryWalker" API.  This Article provides you few examples on how you can use this API in real time.  There might be some other cases where it can be used, but overall, this API gives the Developer a way to build his code to find the record History.

The HistoryWalker API uses the audit/history tables to generate a historical version of an existing record. Before using this API, let’s see how the audit/history table works. 

Behavior/Differences between Audit & History Tables

sys_audit	sys_history_set	sys_history_line
Stores historical information for all records	Identifies record that has historical information from audited table	Stores the actual changes happened to the field values
Deleted records can’t be audited unless you specifically mention in “glide.ui.audit_deleted_tables” system property	-N.A-	-N.A-
The records are kept forever	Deletes Records that have not been updated for last 30 days	Uses the Table Rotation between 4 history tables for every 7 days. Drops history records that are older than 28 days.
Acts as a Source Table for all history records	Generates instantly upon user request	Generates instantly upon user request
-N.A-	In addition, it includes the Journal entries & Information given while insert	In addition, it includes the Journal entries & Information given while insert

Scenario#1

Incident has been assigned to “Adela Cervantsz” and later it was reassigned to “Aileen Mottern”.  “Aileen Mottern” wants to know what fields have been changed by “Adela Cervantsz”.  You can write the code like this 

var incGr = new GlideRecord('incident');

incGr.get('number', 'INC0007002');

var hw = new sn_hw.HistoryWalker(incGr.getTableName(), incGr.getUniqueValue());

hw.walkTo(0);

gs.print("Fields Updated by Adela Cervantsz::");

        do {

            printChangedFields(hw);

        } while (hw.walkForward());



        function printChangedFields(hw) {

            var walkedGr = hw.getWalkedRecord();

            var fields = GlideScriptRecordUtil.get(walkedGr).getChangedFieldNames();

if(walkedGr.sys_updated_by == "adela.cervantsz") {

for (var j = 0; j < fields.size(); j++) {

gs.print(fields.get(j) + "=" + walkedGr.getDisplayValue(fields.get(j)) + "/Updated On " + walkedGr.sys_updated_on);

}

}

}

Scenario#2

You want to know how many times and all the messages posted by the Caller in an Incident. You need to set “setWithJournalFields” to true.

var incGr = new GlideRecord('incident');

        incGr.get('number', 'INC0007002');

        var hw = new sn_hw.HistoryWalker(incGr.getTableName(), incGr.getUniqueValue());

        hw.setWithJournalFields(true);

        hw.walkTo(0);

        do {

            var comments = hw.getWalkedRecord().comments;

            if (hw.getWalkedRecord().sys_updated_by == incGr.caller_id.user_name) {

                gs.print("Comments - " + comments + " - " + hw.getWalkedRecord().sys_updated_on);

            }

        } while (hw.walkForward());

Scenario#3

Catalog Item “Standard Laptop'' was submitted by “Abel Tuter”.  While submitting the request he didn’t select “Adobe Acrobat” Software.  Later he told that to have “Adobe Acrobat” as well.  The Resolver updated this Variable and completed the fulfillment.

Later the Licensing Team found that this software needs a License and requires the PR.  They wanted to find out what exactly happened with that request so that they can take the PR from the Requestor.  You can write something like this

//Standard Laptop Catalog Item

        var ritm = new GlideRecord('sc_req_item');

        ritm.get('number', 'RITM0010010');



        var hw = new sn_hw.HistoryWalker(ritm.getTableName(), ritm.getUniqueValue());

        hw.setWithVariables(true);

        hw.walkTo(0);

        if (hw.walkTo(0)) {

            var acrobat = hw.getWalkedRecord().variables.acrobat;

            gs.print('Acrobat Checkbox value initially was ' + acrobat);

        }

Like this, you can use the HistoryWalker API in some other cases as well.  The Useful Methods available are 

• walkTo -  Walk to specific update
• walkForward - Walk from the beginning of a record
• walkBackward - Walk from Latest update to the initial update of a record
• setWithJournalFields - It includes all the Journal entries while collecting History records
• setWithVariables - It includes all variables while collecting the History records.

Reference

Leave a comment here if you find any real time scenario where you can use this API.

Thanks,

Narsing

[Shane J]

It wasn't obvious to me how to use this to get the Previous value in a background script.  I tried a few different things and got part way there I think.