Showing changes to an Entity (record) object
The following example illustrates how to use the HCL Compass API to get information about field values before and after the user has updated a record. This example is structured as a global hook that can be called from any other hook, such as from the ACTION_COMMIT hook.
VBScript
REM Start of Global Script ShowOldNewValues
REM TODO -- put your script code here
Sub ShowOldNewValues (actionname, hookname)
Dim fieldnames
Dim FN
Dim OldFV
Dim FieldValueStatus
Dim FieldInfo
Dim i
Dim NewFV
Dim FieldType
Dim is_short
M = "'" & actionname & "' action's " & hookname & " script (VB" & _
"version):" & VBCrLf & VBCrLf
' Get a list of the fields in this record type...
fieldnames = GetFieldNames
' Loop through the fields, showing name, type, old/new value...
if IsArray(fieldnames) Then
i = LBound(fieldnames)
Do While i <= UBound(fieldnames)
FN = fieldnames(i)
M = M & FN & ":"
' Get the field's original value...
set FieldInfo = GetFieldOriginalValue(FN)
FieldValueStatus = FieldInfo.GetValueStatus()
If FieldValueStatus = AD_HAS_NO_VALUE Then
OldFV = "<no value>"
ElseIf FieldValueStatus = AD_VALUE_NOT_AVAILABLE Then
OldFV = "<value not available>"
ElseIf FieldValueStatus = AD_HAS_VALUE Then
OldFV = FieldInfo.GetValue()
Else
OldFV = "<Invalid value status: " & FieldValueStatus & ">"
End If
' Get the current value (it may have been updated during
' this action)...
set FieldInfo = GetFieldValue(FN)
FieldValueStatus = FieldInfo.GetValueStatus()
If FieldValueStatus = AD_HAS_NO_VALUE Then
NewFV = "<no value>"
ElseIf FieldValueStatus = AD_VALUE_NOT_AVAILABLE Then
NewFV = "<value not available>"
ElseIf FieldValueStatus = AD_HAS_VALUE Then
NewFV = FieldInfo.GetValue()
Else
NewFV = "<Invalid value status: " & FieldValueStatus & ">"
End If
' Get and reformat the field's type...
FieldType = FieldInfo.GetType()
is_short = 1
If FieldType = AD_SHORT_STRING Then
FieldType = "Short String"
ElseIf FieldType = AD_MULTILINE_STRING Then
FieldType = "Multiline String"
is_short = 0
ElseIf FieldType = AD_INT Then
FieldType = "Integer"
ElseIf FieldType = AD_DATE_TIME Then
FieldType = "Date time"
ElseIf FieldType = AD_REFERENCE Then
FieldType = "Reference"
ElseIf FieldType = AD_REFERENCE_LIST Then
FieldType = "Reference List"
is_short = 0
ElseIf FieldType = AD_ATTACHMENT_LIST Then
FieldType = "Attachment List"
is_short = 0
ElseIf FieldType = AD_ID Then
FieldType = "ID"
ElseIf FieldType = AD_STATE Then
FieldType = "State"
ElseIf FieldType = AD_JOURNAL Then
FieldType = "Journal"
is_short = 0
ElseIf FieldType = AD_DBID Then
FieldType = "DBID"
ElseIf FieldType = AD_STATETYPE Then
FieldType = "STATETYPE"
ElseIf FieldType = AD_RECORDTYPE Then
FieldType = "RECORDTYPE"
Else
FieldType = "<UNKNOWN TYPE: " & FieldType & ">"
is_short = 0
End IF
M = M & " Type=" & FieldType & "."
' Display the results. For the purposes of this example,
' the following values are shown:
' 1. Identify whether the field's value has changed or
' not during the current action and indicate that in
' the output.
' 2. For single-line fields (integer, short_string, etc.)
' show the field's value.
' 3. For single-line fields whose values have changed
' during the current action, show the old and the new
' values.
If OldFV = NewFV Then
M = M & " Value is unchanged."
If is_short = 1 Then
M = M & " Value='" & OldFV & "'"
End If
Else
M = M & " Value has changed."
If is_short = 1 Then
M = M & " Old value='" & OldFV & "' New value='" & _
NewFV & "'"
End If
End If
M = M & VBCrLf
i = i + 1
Loop
Else
M = M & "fieldnames is not an array" & VBCrLf
End If
' At this point you could write this information to a file,
' present it in a message box, or write it to the debug window
' using the session.OutputDebugString() method. Here, is used
' the Windows 'MsgBox' API to present the results to the user
' in a message box (note this only works for the first 1024
' characters of "M" due to limitations in the Windows MsgBox
' API...)
MsgBox M
End Sub
REM End of Global Script ShowOldNewValues
Perl
# Start of Global Script ShowOldNewValues
# ShowOldNewValues: Show field values in the current
# record, drawing attention to fields whose values have changed
# during the current action.
sub ShowOldNewValues {
# $actionname as string
# $hookname as string
my($actionname, $hookname) = @_;
my($M) = "'".$actionname."' action's ".$hookname." script (Perl
version):\n\n";
# Get a list of the fields in this record type
# (NOTE: GetFieldNames() returns a *REFERENCE* to an array)...
my($FieldNamesRef) = $entity->GetFieldNames();
# Loop through the fields, showing name, type, old/new value...
foreach $FN (@$FieldNamesRef) {
$M .= $FN . ":"; # Show the field name...
# Get the field's original value...
$FieldInfo = $entity->GetFieldOriginalValue($FN);
$FieldValueStatus = $FieldInfo->GetValueStatus();
if ($FieldValueStatus == $CQPerlExt::CQ_HAS_NO_VALUE) {
$OldFV = "<no value>";
} elsif ($FieldValueStatus ==
$CQPerlExt::CQ_VALUE_NOT_AVAILABLE) {
$OldFV = "<value not available>";
} elsif ($FieldValueStatus == $CQPerlExt::CQ_HAS_VALUE) {
$OldFV = $FieldInfo->GetValue();
} else {
$OldFV = "<Invalid value status:
" . $FieldValueStatus . ">";
}
# Get the current value (may have been updated during this
# action)...
$FieldInfo = $entity->GetFieldValue($FN);
$FieldValueStatus = $FieldInfo->GetValueStatus();
if ($FieldValueStatus == $CQPerlExt::CQ_HAS_NO_VALUE) {
$NewFV = "<no value>";
} elsif ($FieldValueStatus ==
$CQPerlExt::CQ_VALUE_NOT_AVAILABLE) {
$NewFV = "<value not available>";
} elsif ($FieldValueStatus == $CQPerlExt::CQ_HAS_VALUE) {
$NewFV = $FieldInfo->GetValue();
} else {
$NewFV = "<Invalid value status:
" . $FieldValueStatus . ">";
}
# Get and reformat the field's type...
$FieldType = $FieldInfo->GetType();
$is_short = 1;
if ($FieldType == $CQPerlExt::CQ_SHORT_STRING) {
$FieldType = "Short String";
} elsif ($FieldType == $CQPerlExt::CQ_MULTILINE_STRING) {
$FieldType = "Multiline String";
$is_short = 0;
} elsif ($FieldType == $CQPerlExt::CQ_INT) {
$FieldType = "Integer";
} elsif ($FieldType == $CQPerlExt::CQ_DATE_TIME) {
$FieldType = "Date Time";
} elsif ($FieldType == $CQPerlExt::CQ_REFERENCE) {
$FieldType = "Reference";
} elsif ($FieldType == $CQPerlExt::CQ_REFERENCE_LIST) {
$FieldType = "Reference List";
$is_short = 0;
} elsif ($FieldType == $CQPerlExt::CQ_ATTACHMENT_LIST) {
$FieldType = "Attachment List";
$is_short = 0;
} elsif ($FieldType == $CQPerlExt::CQ_ID) {
$FieldType = "ID";
} elsif ($FieldType == $CQPerlExt::CQ_STATE) {
$FieldType = "State";
} elsif ($FieldType == $CQPerlExt::CQ_JOURNAL) {
$FieldType = "Journal";
$is_short = 0;
} elsif ($FieldType == $CQPerlExt::CQ_DBID) {
$FieldType = "DBID";
} elsif ($FieldType == $CQPerlExt::CQ_STATETYPE) {
$FieldType = "STATETYPE";
} elsif ($FieldType == $CQPerlExt::CQ_RECORDTYPE) {
$FieldType = "RECORDTYPE";
} else {
$FieldType = "<UNKNOWN TYPE: " . $FieldType . ">";
$is_short = 0;
}
$M .= " Type=" . $FieldType . ".";
# Display the results. For the purposes of this example, we
# show values as follows:
# 1. Identify whether the field's value has changed or not
# during the current action and indicate that in the
# output.
# 2. For single-line fields (integer, short_string, etc.)
# show the field's value.
# 3. For single-line fields whose values have changed during
# the current action, show the old and the new values.
if ($OldFV eq $NewFV) {
$M .= " Value is unchanged.";
if ($is_short) {
$M .= " Value='".$OldFV."'";
}
} else {
$M .= " Value has changed.";
if ($is_short) {
$M .= " Old value='".$OldFV."' New
value='".$NewFV."'";
}
}
$M .= "\n";
}
$M .= "\n'".$actionname."' action's notification script
(Perl version) exiting.\n";
# At this point you could write this information to a file,
# present it in a message box, or write it to the debug window
# using $session->OutputDebugString().
# Here is called a subroutine 'DBGOUT' which writes the message
# out to a file and invokes 'Notepad' on it...
DBGOUT($M);
}
# End of Global Script ShowOldNewValues
# Start of Global Script DBGOUT
sub DBGOUT {
my($Msg) = shift;
my($FN) = $ENV{'TEMP'}.'\STDOUT.txt';
open(DBG, ">>$FN") || die "Failed to open $FN";
print DBG ($Msg);
close(DBG);
system("notepad $FN");
system("del $FN");
}
# End of Global Script DBGOUT