Commit

Description

Updates the database with the changes made to the Entity object.

This method commits any changes to the database. Before calling this method, you must validate any changes you made to the Entity object by calling the Validate method. The application can call the Commit method only if the Validate method returns an empty string. After calling the Commit method, on success the Entity is committed to the database and any post-commit hooks (such as notification hooks) are run.

If any error occurs during the commit and before the Entity is committed to the database an exception is thrown; the error is not returned as a String result, and the Entity object remains in the same state as it was before the call to the Commit method. For example, Commit hooks are run after data is written to the database but before the database commit is done. An error returned from a Commit hook results in an exception from the Commit method
If an error occurs after the Entity has been committed to the database (such as a failure of an action notification hook), the error is returned as a String result, and the Entity object is no longer in an editable state.

You can call this method only if the Entity object is editable. To make an existing Entity object editable, call the EditEntity method of the Session object. You can use the IsEditable method of the Entity object to determine if you need to revert the commit operation as part of the exception handling. You may not want to revert for all validation failures, and calling the Revert method does not work after a successful Commit (even if it returns a post-notification warning because the entity has already been committed to the database.

On failure, the method may return a string containing an error message or an exception, depending on what causes the failure. For example, the method returns a string containing an error message for failures such as invalid values set for fields. However, the method throws an exception for other failures, such as trying to change an entity that is not in an editable state. Your code should handle both types of potential failures. See Error checking and validation for more information. The Action commit hook example provides examples of error and exception handling when calling the Commit method.

Note: The Commit method cannot be used in a hook to commit the entity on which the current action was invoked (that is, the current entity).

Syntax

VBScript


 entity.Commit

Perl


 $entity->Commit();

Identifier: Description
entity: An Entity object representing a user data record. Inside a hook, if you omit this part of the syntax, the Entity object corresponding to the current data record is assumed (VBScript only).
Return value: If the Entity object is valid, this method returns the empty String (''). If any validation errors are detected, the String contains an explanation of the problem, suitable for presenting to the user.

Examples

VBScript


 ' Modify the record and then commit the changes.
 set sessionObj = GetSession
 set entityObj = sessionObj.GetEntity("defect", "BUGID00000042")
 sessionObj.EditEntity entityObj, "modify"
 
 ' ... modify the Entity object
 ' your code should also check for exceptions
 status = entityObj.Validate 
 
      if status = "" then
          status =    entityObj.Commit 
          if status = "" then 
             ' successful commit
          else
             'check error message
          end if
 
        else
          entityObj.Revert  
        end if
 ' The Entity object is no longer editable

Perl

# Modify the record and then commit the changes.
 $sessionObj = $entity->GetSession();
 
 $entityObj = $sessionobj->GetEntity("defect","BUGID00000042");
 
 $sessionObj->EditEntity($entityobj,"modify");
 
 # Modify the entity object
 # Your code should also check for exceptions
 $status = $entityObj->Validate();
 
    if ($status == ""){
       $status = $entityObj->Commit();
       if ($status == ""){
          # successful commit
       }
       else {
          # check error message
          }
    else {
          $entityObj->Revert();
       }

 # The entity object is no longer editable.