The GSU_CQXE_OpenForm and GSU_CQXE_OpenSubmitForm global hooks provide the ability to open prepopulated forms from hooks. After you add the global hooks to your schema, you can access them to specify the record type of the form and initialize it with field values.
This functionality is available in ClearQuest® Client and ClearQuest Web. If a user attempts to open a form from an older client, or from the ClearQuest client for Windows, the API will return an informational message. To display this message to the user, call the die function.
If the client supports this feature, the API will throw an exception, and any code after the API call is not executed. Use the callback hooks in the script to run additional code after the API call.
For more information about applying packages, see Applying packages.
Use these examples of record and action scripts with the global hooks to provide users with prepopulated forms. In this example, the CreateChildDefect action opens a submit form that is prepopulated with the values from the Record Script hook. The user can cancel or save the form, which executes the code in the RecordScriptCancel and RecordScriptSave hooks.
sub Defect_RecordScript {
my($result);
my($param) = @_;
# record type name is Defect
$currentSession= $entity->GetSession();
$newentity = $currentSession->BuildEntity("Defect");
$headline = $entity->GetFieldValue("Headline")->GetValue();
$id = $entity->GetFieldValue("id")->GetValue();
$newentity->SetFieldValue("Headline", "Child Of [".$id."] ".$headline);
$newentity->SetFieldValue("Severity", "3-Average");
# For multiple-line (Choice list) values
$newentity->SetFieldValue("Symptoms", "Data Loss\nSlow Performance");
# For reference-list fields
$newentity->AddFieldValue("customer", "123 smith");
$newentity->AddFieldValue("customer", "Ethan Hunt");
# For Date fieldType
$newentity->SetFieldValue("dateTime", "2010-04-08 15:57:28");
# For multiple-line (textArea) fieldType, support "\n","\t"special characters
$newentity->SetFieldValue("Description", "Description");
# Call back hooks need be defined in "record scripts" under $recordType
$save_callback_hook_name="RecordScriptSave";
# Set the orders of the fields, must include all field names
$fieldOrder = ["Headline","Severity","Symptoms","customer","dateTime","Description"];
$returnValue=GSU_CQXE_OpenSubmitForm($newentity,$save_callback_hook_name, "RecordScriptCancel", $fieldOrder);
if($returnValue){
# If the client doesn't support the global hook, execute the hooks there,
# e.g. validate and submit $newentity
# Win32::MsgBox("This function is not supported by the client.");
}
return $result;
}
sub Defect_RecordScriptSave {
my($result);
my($param) = @_;
# record type name is Defect
@params = split (/\n+/, $param);
$entity->EditEntity("Modify");
$entity->AddFieldValue("children",$params[1]);
$entity->Validate();
$entity->Commit();
return $result;
}
sub Defect_RecordScriptCancel {
my($result);
my($param) = @_;
# record type name is Defect
$error_summary="CancelBackSaveHook";
$error_details="No parameters were specified.";
# $result=&DieWithCustomMessage;("ERROR",$error_summary, $error_details);
DieWithCustomMessage("INFO", $error_summary, $error_details);
return $result;
}
Function Defect_RecordScript(param)
' param As Variant
' record type name is Defect
Dim currentSession
Dim newentity
Dim this_entity
Dim fieldOrder
Dim returnValue
Dim saveHookName
Dim cancelHookName
set currentSession = GetSession
set newentity= currentSession.BuildEntity ("defect")
newentity.SetFieldValue "Headline", "Child Of parent record "
newentity.SetFieldValue "Severity", "3-Average"
' For multiple-line (Choice list) values
newentity.AddFieldValue "Symptoms", "Data Loss"
newentity.AddFieldValue "Symptoms", "Slow Performance"
' For reference-list fields
newentity.AddFieldValue "customer", "Ethan Hunt"
' For Date fieldType
newentity.SetFieldValue "dateTime", "2010-04-08 15:57:28"
' For multiple-line (textArea) fieldType, support vbcrlf special characters
newentity.SetFieldValue "Description", "Data Loss" & vbcrlf & "Slow Performance Unexpected Behavior" & vbcrlf & "retr"
ReDim fieldOrder(6) 'This sets up an array of seven elements with subscripts from 0 to 5
fieldOrder(0)="Headline"
fieldOrder(1)="Severity"
fieldOrder(2)="Symptoms"
fieldOrder(3)="customer"
fieldOrder(4)="dateTime"
fieldOrder(5)="Description"
saveHookName="RecordScriptSave"
cancelHookName="RecordScriptCancel"
Defect_RecordScript=GSU_CQXE_OpenSubmitForm(newentity,saveHookName,cancelHookName,fieldOrder)
If Defect_RecordScript <> "" then
' If the client doesn't support the global hook, excute the hooks there,
' e.g. validate and submit $newentity
' MsgBox "This function is not supported by the client."
End If
End Function
Function Defect_RecordScriptSave(param)
' param As Variant
' record type name is Defect
REM add your hook code here
Dim error_summary
Dim error_details
error_summary="Submit record has been saved."
error_details="The submit record information is:" & param
call DieWithCustomMessage("INFO", error_summary, error_details)
End Function
Function Defect_RecordScriptCancel(param)
' param As Variant
' record type name is Defect
REM add your hook code here
Dim error_summary
Dim error_details
error_summary="CancelBackSaveHook"
error_details="No parameters were specified."
call DieWithCustomMessage("INFO",error_summary, error_details)
End Function