How to generate a custom message with the ClearQuest API

Answer

The ClearQuest Client and ClearQuest Web Client allow hooks to present error, warning, and information alert messages to users by embedding the alert message parameters within a normal hook error message. However, because the ClearQuest for Windows client, user-written scripts, and older clients might not recognize the alert message parameters, this capability should be accessed through the global hook below, after adding it to your schema. The hook uses the message parameters in a normal die statement if the client does not support custom messages, but dies with a custom message if the client supports it.

Note: For ClearQuest releases 7.1.x - 7.1.2.3, the DieWithCustomMessage functionality is only supported in the ClearQuest Web Client.. Product defect APAR PM32456 has been filed to fix this functionality for the Rational ClearQuest Client.

The DieWithCustomMessage function below can be called from all places where a die statement can be used, and it will have the same effect as a die statement on the current operation. For example, calling the DieWithCustomMessage function from an access control hook would indicate failure in exactly the same way a die statement would indicate failure, but with a custom message.

Note: The following code was updated for ClearQuest version 7.1.1.2. If you used the code that was provided with ClearQuest version 7.1 and 7.1.1.1, please update your schema with the latest code.

Perl global hook


# DieWithCustomMessage( $msg_type, $msg_summary, $msg_details )
#
# This is a global hook that can be called from any record
# script to generate a message with the specified
# $msg_type, $msg_summary and $msg_details strings. If the
# current ClearQuest client does not support custom messages,
# the specified $msg_type, $msg_summary and $msg_details will
# be embedded in the standard hook error message.
#
# $msg_type has three legal values: INFO, WARNING, and ERROR.
# For each type, the corresponding title and icon will appear
# in the title of the message box.
#
# In field and action hooks, only ERROR should be used. These
# hooks throw exceptions to generate the custom message,
# and exceptions should only be thrown when there is an error.
#
# For named hooks and record script alias, INFO and WARNING can
# be used to indicate different kinds of messages to inform
# users about the result of named hooks or record script alias.
#
sub DieWithCustomMessage($$$)
{
# die normally if the CQ client does not support MSG_TYPE,
# MSG_SUMMARY and MSG_DETAILS
my ( $type, $summary, $details) = @_;
my %cqxe;
foreach my $name ( qw( DOC_BEGIN DOC_CLOSE
GENERATE_CUSTOM_MESSAGE_BEGIN GENERATE_CUSTOM_MESSAGE_CLOSE
MSG_SUMMARY_BEGIN MSG_SUMMARY_CLOSE
MSG_DETAILS_BEGIN MSG_DETAILS_CLOSE
MSG_TYPE_BEGIN MSG_TYPE_CLOSE ) )
{
my $value = $::session->GetNameValue( "_CQXE_$name" );
if ( ! $value )
{
die( "(session variable '_CQXE_$name' not
set)\n\n$type\n$summary\n$details\n\n" );
}
$cqxe{ $name } = $value;
}

# the '<' ,'&',">","'",""" characters are
# not allowed in XML
foreach ($summary, $details, $type)
{
s/\&/\&amp\;/g;
s/\</\&lt\;/g;
s/\>/\&gt\;/g;
s/\'/\&apos\;/g;
s/\"/\&quot\;/g;
}

# use CQXE to set the message summary, details and type
die( $cqxe{DOC_BEGIN}
. $cqxe{GENERATE_CUSTOM_MESSAGE_BEGIN}
. $cqxe{MSG_TYPE_BEGIN} . $type . $cqxe{MSG_TYPE_CLOSE}
. $cqxe{MSG_SUMMARY_BEGIN} . $summary . $cqxe{MSG_SUMMARY_CLOSE}
. $cqxe{MSG_DETAILS_BEGIN} . $details . $cqxe{MSG_DETAILS_CLOSE}
. $cqxe{GENERATE_CUSTOM_MESSAGE_CLOSE}
. $cqxe{DOC_CLOSE} );
}


Perl examples


sub Defect_generate_error_message {
my($result);
my($param) = @_;
# record type name is Defect
$error_summary="ReturnCustomErrorMessage";
$error_details="Error message: Clicking this button will activate a computer virus!";
# $result=&DieWithCustomMessage($error_summary, $error_details,"ERROR");
DieWithCustomMessage("ERROR",$error_summary, $error_details);
return $result;
}

sub Defect_generate_warning_message {
my($result);
my($param) = @_;
# record type name is Defect
$error_summary="ReturnCustomWarningMessage";
$error_details="Warning message: Do not smoke at the work place!";
DieWithCustomMessage("WARNING",$error_summary, $error_details);
return $result;
}

sub Defect_generate_info_message {
my($result);
my($param) = @_;
# record type name is Defect
$error_summary="ReturnCustomInfoMessage";
$error_details="Information message: Welcome to Beijing!";
DieWithCustomMessage("INFO",$error_summary, $error_details);
return $result;
}



VBScript global hook


' DieWithCustomMessage( $msg_type, $msg_summary, $msg_details )
'
' This is a global hook that can be called from any record
' script to generate a message with the specified
' $msg_type, $msg_summary and $msg_details strings. If the
' current ClearQuest client does not support custom messages,
' the specified $msg_type, $msg_summary and $msg_details will
' be embedded in the standard hook error message.
'
' $msg_type has three legal values: INFO, WARNING, and ERROR.
' For each type, the corresponding title and icon will appear
' in the title of the message box.
'
' In field and action hooks, only ERROR should be used. These
' hooks throw exceptions to generate the custom message,
' and exceptions should only be thrown when there is an error.
'
' For named hooks and record script alias, INFO and WARNING can
' be used to indicate different kinds of messages to inform
' users about the result of named hooks or record script alias.
'
Function DieWithCustomMessage (msg_Type, msg_Summary, msg_Details)
Dim propertyKeys(10)
Dim session
Dim i,j,value
Dim dieOutStr

set session= GetSession

propertyKeys(0)="DOC_BEGIN"
propertyKeys(1)="DOC_CLOSE"
propertyKeys(2)="GENERATE_CUSTOM_MESSAGE_BEGIN"
propertyKeys(3)="GENERATE_CUSTOM_MESSAGE_CLOSE"
propertyKeys(4)="MSG_SUMMARY_BEGIN"
propertyKeys(5)="MSG_SUMMARY_CLOSE"
propertyKeys(6)="MSG_DETAILS_BEGIN"
propertyKeys(7)="MSG_DETAILS_CLOSE"
propertyKeys(8)="MSG_TYPE_BEGIN"
propertyKeys(9)="MSG_TYPE_CLOSE"

' die normally if the CQ client does not support MSG_TYPE,
' MSG_SUMMARY and MSG_DETAILS
For i = 0 To 9 Step 1
value = session.NameValue( "_CQXE_" & propertyKeys(i))
if len(value)=0 then
Err.Raise 6,"Initialize error", "(session variable '_CQXE_" + propertyKeys(i) + "' not set)\n\n" + msg_Type + "\n" + msg_Summary + "\n"+ msg_Details + "\n\n"
exit Function
end if
Next

' the '<' ,'&',">","'",""" characters
' are not allowed in XML
msg_Summary= replaceXMLSpecialChar(msg_Summary)
msg_Details= replaceXMLSpecialChar(msg_Details)
msg_Type= replaceXMLSpecialChar(msg_Type)


' use CQXE to set the message msg_type, summary and details
dieOutStr=session.NameValue("_CQXE_" & propertyKeys(0))
dieOutStr=dieOutStr & session.NameValue("_CQXE_" & propertyKeys(2))
dieOutStr=dieOutStr & session.NameValue("_CQXE_" & propertyKeys(8)) & msg_Type & session.NameValue("_CQXE_" & propertyKeys(9))
dieOutStr=dieOutStr & session.NameValue("_CQXE_" & propertyKeys(4)) & msg_Summary & session.NameValue("_CQXE_" & propertyKeys(5))
dieOutStr=dieOutStr & session.NameValue("_CQXE_" & propertyKeys(6)) & msg_Details & session.NameValue("_CQXE_" & propertyKeys(7))
dieOutStr=dieOutStr & session.NameValue("_CQXE_" & propertyKeys(3))
dieOutStr=dieOutStr & session.NameValue("_CQXE_" & propertyKeys(1))


Err.Raise 6,"Throw customer messages", dieOutStr ' Raise an overflow error.
end Function

' the '<' ,'&',">","'",""" characters
' are not allowed in XML
Function replaceXMLSpecialChar(xmlValue)
xmlValue= replace(xmlValue,"<","&lt;")
xmlValue= replace(xmlValue,"&","&amp;")
xmlValue= replace(xmlValue,">","&gt;")
xmlValue= replace(xmlValue,"'","&apos;")
xmlValue= replace(xmlValue,"""","&quot;")
replaceXMLSpecialChar= xmlValue
end Function


VBScript examples


Function recordtype_ErrorMessage(param)
' param As Variant
' record type name is recordtype
REM add your hook code here
Dim error_summary
Dim error_details
error_summary="ReturnCustomErrorMessage"
error_details="Error message: Clicking this button will activate a computer virus!"
' $result=&DieWithCustomMessage($error_summary, $error_details,"ERROR");
call DieWithCustomMessage("ERROR",error_summary, error_details)

End Function

Function recordtype_InfoMessage(param)
' param As Variant
' record type name is recordtype
REM add your hook code here
Dim error_summary
Dim error_details

error_summary="ReturnCustomInfoMessage"
error_details="Information message: Welcome to Beijing!"
call DieWithCustomMessage("INFO",error_summary, error_details)
End Function

Function recordtype_WarningMessage(param)
' param As Variant
' record type name is recordtype
REM add your hook code here
Dim error_summary
Dim error_details
error_summary="ReturnCustomWarningMessage"
error_details="Warning message: Do not smoke at the work place!"
call DieWithCustomMessage("WARNING",error_summary, error_details)
End Function