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 the DevOps Plan application. If a user attempts to open a form from an older application, the API will return an informational message. To display this message to the user, call the die function.

If the application 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.

Note: The 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.
The 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.
  1. In the DevOps Plan 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.
  2. Expand the GlobalScriptUtility node in the list of packages and select version 1.0. Click Next.
  3. Select the record types where you want to apply the package. Click Finish.
The GlobalScriptUtility package is now applied to the schema you selected. To verify the package installation, look for the new GSU_CQXE global script in the schema.

Example

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.

To use this example, make the following changes to your schema:
  1. Add two new fields to the Defect record type: a DATE_TIME field named dateTime, and a REFERENCE_LIST field named children.
  2. Set the Reference To attribute of the children field to Defect.
  3. Create three record scripts named RecordScript, RecordScriptSave, and RecordScriptCancel, using the example Perl code below.
  4. Add a new RECORD_SCRIPT_ALIAS action, named CreateChildDefect, to the Defect record type. Set the CreateChildDefect action to use the RecordScript hook you created above.
  5. Add a new tab, named OpenForm, to the Defect_Base form in the Defect record type.
  6. 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.
Note: Some of these code examples use the 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 application 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 application.");
	}
    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;
}