Action commit hook example

Commit hooks perform additional actions before a record is committed to the database.

The following example checks whether a defect has duplicates (dups). If the original defect was marked as tested, the hook marks the duplicates as dupdone, indicating that they should be evaluated again to verify that they are fixed. If there is a failure to commit one of these updates, all database transactions are rolled back, including the one to which this hook belongs.

Note: You can also perform the additional actions in a Validation or Notification hook. When calling the Validate and Commit methods, make sure your code checks for exceptions and return message strings. The examples in this section provide examples of error and exception handling. See Error checking and validation You can also use the IsEditable method of the Entity object to validate records updated with an EditEntry action. If the EditEntry action fails is you might need to revert the commit operation as part of the exception handling. However you might not want to revert for all validation failures. Calling the Revert method does not work after a successful commit, even if the operation returns a post-notification warning because the Entity is already committed to the database.

VBScript

Sub swbug_Commit(actionname, actiontype)

    ' actionname As String
    ' actiontype As Long
    ' action = tested
    Dim dups  ' Array of all direct duplicates of this defect
    Dim dupsvar ' Variant containing link to a duplicate
    Dim dupsobj ' The same link, but as an object rather than a variant
    Dim record  ' The record extracted from the link
    Dim session
    Dim parent_id ' The display name of this defect
    Dim RetVal

    ' Make an API to call to see if this record has duplicates
    If HasDuplicates() Then
      Set session = GetSession
      dups = GetDuplicates
      parent_id = GetDisplayName

      For Each dupvar In dups
        Set dupobj = dupvar
        Set entity = dupobj.GetChildEntity
        session.EditEntity entity, "dupdone"
        entity.SetFieldValue "action_reason", "Original " & parent_id & " is tested"

       ' validate and commit, with exception and error handling
       On Error Resume Next
       Err.Clear
       'RetVal is empty on success else it holds an error message string on failure
       RetVal = entity.Validate  
       if Err.Number <> 0  then       
      ' An exception occurred
      ' Err.description holds the error message 
      ' This example prints the error details and reverts the record to
      ' its previous state.
       StdOut "Validation exception:" & vbCrLf &_
        "    Error number: " & Err.Number & vbCrLf &_
        "    Error description: '" & Err.Description & vbCrLf
     entity.Revert  

elseif RetVal <> "" then  
    ' An error message string was returned.indicating that validation failed, 
    ' possibly due to one or more fields having unacceptable values. You can
    ' attempt to resolve this problem by determining which fields
    ' have unacceptable values, give them acceptable values, and retry the
    ' call to entity.Validate. This code example prints the error
    ' details and then reverts the record to its original state.
    StdOut "Validation error: " & RetVal & vbCrLf  
    entity.Revert

else 
    ' Validate was successful. You can proceed and Commit the change.
    StdOut "Validation was successful." & vbCrLf   
    Err.Clear
    RetVal = entity.Commit  
    if  Err.Number <> 0  then       
        ' An exception occurred (this indicates that an error occurred before
        ' the values were written to the database). This example code prints the
        ' error details and reverts the record to its previous state.
        StdOut "Commit exception:" & vbCrLf &_
            "    Error number: " & Err.Number & vbCrLf &_
            "    Error description: '" & Err.Description & vbCrLf
        entity.Revert

    elseif RetVal <> "" then 
        ' An error message string value was returned. This indicates that an 
        ' error occurred after the values were written to the database (for 
        ' example, a failure in an action notification hook). You can handle 
        ' the error by correcting the failure and trying  to commit again or 
        ' revert. This example code prints the error message details.
        StdOut "Commit error (after committing changes): " & RetVal & vbCrLf

    else
        ' No exception or returned error message value
        StdOut "Commit was successful." & vbCrLf
    end if   
end if 

' Clear the error handler
Err.Clear

      Next
    end if
End Sub

Perl

sub swbug_Commit {

    my($actionname, $actiontype) = @_;

    # $actionname As string scalar
    # $actiontype as long scalar
    # action is Submit
    # This hook is fired during the "commit" step of an
    # entity update. It is the appropriate place to put an
    # activity which should be bundled into the same
    # transaction as the commit, such as subactions
    # or updates of external data storage.

    my ($RetVal);
    my ($dups, # Array of all direct duplicates of this defect
    $record,   # The record extracted from the link
    $parent_id, # The display name of this defect 
    $session,
    $locEntity,
    $dupobj
    );

    # Make an API to call to see if this record has duplicates
    if ($entity->HasDuplicates()) {
      $session = $entity->GetSession();
      $dups = $entity->GetDuplicates();
      $parent_id = $entity->GetDisplayName();
      my $count = $dups->Count();
      my $i = 0;
      for ($i=0;$i<$count;$i++){
        $dupobj = $dups->Item($i);
        $locEntity = $dupobj->GetChildEntity();
        $session->EditEntity($locEntity, "dupdone");
        $locEntity->SetFieldValue("action_reason", "Original " 
              . $parent_id . " is tested");

    # validate and commit, with exception and error handling
      eval {$RetVal = $locEntity->Validate(); };
      if ($@){
           print "Exception: '$@'\n";
           $locEntity->Revert();
      }
      elsif ($RetVal ne "") { 
          $session->OutputDebugString ("validation error: $RetVal\n"); 
          # correct whatever failed validation and then try validate again or revert
          }    
      else {
            eval {$RetVal = $locEntity->Commit(); }; 
            if ($@){
                    print "Exception: '$@'\n";
                    $locEntity->Revert();
                     }
            elsif ($RetVal ne "") { 
            $session->OutputDebugString ("commit error: $RetVal\n"); 
            # handle error - correct whatever failed and try again or revert  
                }
        # commit successful
            }
    }
   } 
}