Opening a prepopulated form
Description
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 HCL Compass Client
and HCL Compass Web.
If a user attempts to open a form from an older client, or from the Compass 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.
GSU_CQXE_OpenSubmitForm
API
require a temporary CQEntitiy object, which uses a database ID. For
better performance, you can use the GSU_CQXE_SubmitForm
database
ID for this function, use the GSU_CQXE_SubmitRecord API to open forms.
For details, see Opening a prepopulated form with the GSU_CQXE_SubmitRecord API.GSU_CQXE_OpenForm
and GSU_CQXE_OpenSubmitForm
global
hook functions are provided in the GlobalScriptUtility (GSU_CQXE
)
package. You must apply this package before you can use these functions.- In the HCL Compass Designer, right-click the version of the schema where you want to apply the package, and then click Packages > Apply Package. The Package Wizard opens.
- Expand the GlobalScriptUtility node in the list of packages and select version 1.0. Click Next.
- Select the record types where you want to apply the package. Click Finish.
GSU_CQXE
global
script in the schema.For more information about applying packages, see Applying packages topic.
Examples
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.
- Add two new fields to the Defect record type: a DATE_TIME field
named
dateTime
, and a REFERENCE_LIST field namedchildren
. - Set the Reference To attribute of the
children
field to Defect. - Create three record scripts named
RecordScript
,RecordScriptSave
, andRecordScriptCancel
, using the example Perl or VBScript code below. - Add a new RECORD_SCRIPT_ALIAS action, named
CreateChildDefect
, to the Defect record type. Set theCreateChildDefect
action to use theRecordScript
hook you created above. - Add a new tab, named
OpenForm
, to the Defect_Base form in the Defect record type. - On the new OpenForm tab, add the following controls:
- A Text Field, set to display both the Date and Time. Select Long Date for the date display format. Select dateTime for the source field.
- A Parent/Child control with the source field set to children.
DieWithCustomMessage
function
to handle error messages returned by the API. For more information
about this global script, see Generating a custom error message.Perl examples
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;
}
VBScript examples
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
You can save the record if you comment out the following line of vbscript code, in the RecordScriptSave function in the vbscript example call DieWithCustomMessage("INFO", error_summary, error_details) so that it has a single quote in front of the line of code ' call DieWithCustomMessage("INFO", error_summary, error_details). Note that the ' in front of the line of code causes to be commented out and not run.
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