Saving your changes

Committing changes to the database is a two-step process where you first validate the record you changed or created, and then commit the change.

About this task

After you create or edit a record, save your changes to the database by following these steps:

Validate data in the record by calling the Validate method of the Entity object. This method returns any validation errors so that you can fix them before you attempt to save your changes.
Call the Commit method of the Entity object. This method writes the changes to the database, ends the current action, and checks in the record so that it cannot be edited.

The Validate method runs the schema's validation scripts and returns a string containing any validation errors. If this string is not empty, you can use the GetInvalidFieldValues method to return a list of fields that contain data that are not correct. After fixing the values in these fields, you must call Validate again. If the Validate method returns an empty string, there are no more errors.

After you validate the record, and the validation succeeds, you commit your changes to the database by calling the Commit method of the corresponding Entity object.

Reverting your changes: If validation of a record fails, you cannot commit the changes to the database. The safest solution is to revert the record to its original state and report an error. To revert a record, call the Revert method of the Entity object.

Reverting a set of changes returns the record to the state it was in before you called EditEntity. If you revert the changes made to an Entity object created by the BuildEntity method, the record is not created and the data is discarded. IDs associated with records are not recycled. If you revert a record that was made editable by the BuildEntity method, the record is discarded but its visible ID is not discarded so that future records cannot use that ID.

Here is an example of the steps to change the state of a record:

Begin the action using the EditEntity($Entity, action-name) method.
Modify field values and check field-level validity.
Validate the state of the record (using the Validate method).
Commit the changes if there are no errors (using the Commit method).
To cancel the action use the Revert method.

Example

# Modify the record and then commit the changes. 
$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.

< Previous | Next >