JournalRedactor

JournalRedactor can be used to redact or delete journal entries that may contain sensitive or private information, or customer PII. JournalRedactor can be instantiated using the new keyword once the Script Include has been installed; as in var redactor = new JournalRedactor(). If you're curious, you can find the code in this script (as of v1.3) in this Gist. 

Full article with detailed explanation here!

Note: Many organizations have legal requirements for data retention, and redaction (or especially deletion) may be the sort of thing that requires approval from your legal department. It is strongly recommended that you consult your legal department for your use-case before implementing this API in your organization, and possibly even limit the usage of this API to specific roles, depending on your company's legal obligations. 

The parameters listed below, are the parameters that should be passed in when instantiating an object of this class. See example usage for more info.

The XML download link can be found at the bottom of this page. 

Parameters

 Name Type Required Description
journalEntryID String No

The sys_id of a specific record in the sys_journal_field table corresponding to the journal entry you'd like to redact or delete. You can also specify this via the .setJournalID() method. 
If you don't know the sys_id of the journal entry's sys_journal_field record, you can find it by calling the .findJournalID() method.

Example

//Method 1:
var journalID = '8521de9b3710230090b68cf6c3990ebc'; //sys_id of a record in the sys_journal_field record
var redactor = new JournalRedactor(journalID);
//...

//Method 2:
var redactor = new JournalRedactor(); 
//...
/*
    Instantiating without a journal record ID means you'll need to call 
    .setJournalID() or .findJournalID() before you can redact.
*/

redact()

The redact() method can be called with either one or two arguments. If only one is specified (the deleteEntry parameter), it must be set to true. If two arguments are specified, the first should be set to false. The deleteEntry parameter exists largely to prevent unintentional deletions. 

Note: Before this method can be called, you must have either (1) specified a sys_journal_field record sys_id in the constructor, or by using the .setJournalID() method, or (2) found the journal record by using the .findJournalID() method.

Parameters

 Name Type Required Description
deleteEntry Boolean Yes

True/false depending on whether or not the journal entry should be deleted as opposed to updated to something else.
If set to true, the second parameter (newValue) is not required, and the journal entry will be deleted completely. If set to false, the second parameter (newValue) is required, as the redaction cannot complete without having something to replace the redacted journal text with. 
newValue String No

This parameter is only required if deleteEntry is set to false, in which case this string will replace the entire journal entry. For example, if the current journal entry contains the text "My name is Tim", you might specify "My name is [redacted]" for the newValue parameter.

Output

This method returns a boolean value, indicating whether the redaction was successful. If false is returned, an error or warning should have been logged to the system logs. You can see more info about what might have caused the issue by using the Script Debugger in ServiceNow, or by calling the .setVerbose() method, and passing in true. 

Example

//Method 1: Simply delete the journal entry
var journalID = '8521de9b3710230090b68cf6c3990ebc'; //sys_id of a record in the sys_journal_field record
var redactor = new JournalRedactor(journalID);
redactor.redact(true);

//Method 2: Replace the journal entry with different text
var journalID = '8521de9b3710230090b68cf6c3990ebc'; //sys_id of a record in the sys_journal_field record
var redactor = new JournalRedactor(journalID);
redactor.redact(false, 'The customer\'s social security number is [REDACTED].');

setJournalID()

This method allows you to explicitly set the journal entry you'd like to redact by specifying the sys_id of that record in the sys_journal_field table. You can also specify this in the constructor, as you can see in the first example on this page. If you don't know the journal entry sys_id, you can use the .findJournalID() method described below.

Parameters

 Name Type Required Description
journalEntryID String Yes

The sys_id of the record in the sys_journal_field table, corresponding to the journal entry you'd like to redact. 

Example

var redactor = new JournalRedactor();
redactor.setJournalID('8521de9b3710230090b68cf6c3990ebc');
redactor.redact(false, 'The customer\'s social security number is [REDACTED].');

findJournalID()

Use this method if you don't already know the sys_id of the sys_journal_field record corresponding to the journal entry you'd like to redact or delete. This will grab all the necessary data

This method accepts two, three, or four arguments (see the table below for a description of each argument).

Parameters

 Name Type Required Description
recordID String Yes

The sys_id of the record on which the journal field resides (not the sys_id of the journal entry itself). For example, if there is a comment on INC0012345 that I want to redact, I would specify the sys_id of the INC0012345 record.
journalText String Yes The exact and complete text of the journal entry you'd like to redact. That is, the current text; not the text you'd like to replace it with.
targetTableName String No Optional: The table that the record on which the journal field resides is in. For example: 'incident' or 'sc_req_item'.
journalFieldName String No The name of the journal field into which the entry to be redacted was entered. For example: 'work_notes', or 'comments'. 

Output

This method returns a boolean, indicating whether the journal entry was successfully found or not. 

Example

var targetRecordID = '1c741bd70b2322007518478d83673af3'; //sys_id of the record on which the journal entry resides
var oldJournalText = 'customer social is 123-45-6789'; //The EXACT, COMPLETE text of the journal entry to be redacted.
var targetRecordTableName = 'incident';
var targetJournalFieldName = 'work_notes';
var redactor = new JournalRedactor();

//Method 1: 2 parameters
redactor.findJournalID(targetRecordID, oldJournalText);
//Method 2: 3 parameters
redactor.findJournalID(targetRecordID, oldJournalText, targetRecordTableName);
//Method 3: 4 parameters
redactor.findJournalID(targetRecordID, oldJournalText, targetRecordTableName, targetJournalFieldName);
//(You only need to use one of the three methods above)

redactor.redact(false, 'The customer\'s social security number is [REDACTED].');

Note: Since this method returns a boolean, you might also want to put a condition block in there to make sure it's successful before attempting the redaction (which would fail):

var targetRecordID = '1c741bd70b2322007518478d83673af3'; 
var oldJournalText = 'customer social is 123-45-6789'; 
var redactor = new JournalRedactor();

if (redactor.findJournalID(targetRecordID, oldJournalText)) {
    redactor.redact(true);
} else {
    //Failed to locate journal ID
}

setVerbose()

This method simply enables additional logging if true is passed in, or disables that logging if false is provided. 

Parameters

 Name Type Required Description
b Boolean Yes

Sets the _verbose property to true, meaning that additional logging is enabled for this instantiation of JournalRedactor

Example

var targetRecordID = '1c741bd70b2322007518478d83673af3';
var oldJournalText = 'customer social is 123-45-6789';
var redactor = new JournalRedactor();
redactor.setVerbose(true); //enable additional logging

if (redactor.findJournalID(targetRecordID, oldJournalText)) {
    redactor.redact(true);
} else {
    //Failed to locate journal ID
}
qEipJ6k[1].png

To deploy JournalRedactor in your ServiceNow instance, follow these steps:

  1. Download the XML file from the link above

  2. Navigate to your Script Includes table (sys_script_include), right-click in the table header, and click Import XML.

  3. On the next page, click Choose File, and select the XML file you've just downloaded.

  4. Finally, click Upload.


You can now use JournalRedactor from any server-side script or scope. 

If you prefer to simply copy-and-paste the code into a new Script Include in your environment, you can do so from the Code section of this page.

Changelog

  • v1.3

    • Fixed an occasional bug where the redactor would throw an error “journalEntryData not ready for redaction…” when the journal entry should be deleted instead of altered.

  • V1.2

    • Added support for redacting in one quick go without needing a “new value” to replace the journal entry with.

    • Started work on upcoming feature: Will soon be able to redact emails and other sys_history_line sort of stuff. Watch this space.

  • v1.1

    • Added loads more JSDoc and info on all public methods, and made logging more effective when verbose mode is enabled.

  • v1.0

    • Initial release

Code

Below, you can see the exact code in the Gist, which you can copy and paste into your environment if you prefer that over importing the XML for the Script Include using the above instructions.