getDeleted()

Syntax

GetDeletedResult = connection.getDeleted(string sObjectType, dateTime startDate, dateTime EndDate);

Usage

Use getDeleted() for data replication applications to retrieve a list of records that have been deleted from your organization's data within the specified timespan. The getDeleted() call retrieves a GetDeletedResult object that contains an array of DeletedRecord objects containing the ID of each deleted record and the date/time (Coordinated Universal Time (UTC) time zone) on which it was deleted. Be sure to read Data Replication before using getDeleted() in your client applications. (For information on IDs, see ID Field Type.)

As of release 8.0, the getDeleted() call respects the user's sharing model.

Rules and Guidelines

When replicating deleted records, consider the following rules and guidelines:

• The specified startDate must chronologically precede the specified endDate value by more than one minute. The specified startDate can’t be the same value as, or later than, the specified endDate value. Otherwise, the API returns an INVALID_REPLICATION_DATE error.
• Records are returned only if the user has access to them.
• Results are returned for no more than 15 days previous to the day the call is executed (or earlier if an administrator has purged the Recycle Bin). If the purge has been performed before your getDeleted() call is executed, an INVALID_REPLICATION_DATE error is returned.
• If latestDateCovered is more than endDate, the call fails, returning an INVALID_REPLICATION_DATE error with the value of latestDateCovered.
• Deleted records are written to a delete log, which getDeleted() accesses. A background process that runs every two hours purges records that have been in an organization's delete log for more than two hours if the number of records is above a certain limit. Starting with the oldest records, the process purges delete log entries until the delete log is back below the limit. This process protects Salesforce from performance issues related to massive delete logs. The limit is calculated using this formula:
  5000 * number of licenses in the organization

  For example, an organization with 1,000 licenses could have up to 5,000,000 (five million) records in the delete log before any purging took place. If purging has been performed before your getDeleted() call is executed, an INVALID_REPLICATION_DATE error is returned. If you get this exception, do a full pull of the table.

• If you delete a large number of records, your data replication runs more frequently than every two hours to ensure getDeleted() returns all records.
• Client applications typically poll for changed data periodically. For important polling considerations, see Polling for Changes.
• Records for certain objects can’t be replicated via the API. To replicate a record via the getDeleted() call, its object must be configured as replicateable (replicateable is true). To determine whether a given object can be replicated, your client application can invoke the describeSObjects() call on the object and inspect its replicateable property.
• Development tools differ in the way that they handle time data. Some development tools report the local time, while others report only the Coordinated Universal Time (UTC) time. To determine how your development tool handles time values, refer to its documentation.
• If you call getDeleted() for a history object, the call returns the records deleted during the given date range for all history objects, not only the history object you specified. For example, if you call getDeleted() for AccountHistory, you'll get records deleted during the given date range for AccountHistory, ContactHistory, and so on. However, getDeleted() calls on OpportunityHistory return only deleted OpportunityHistory records, not other associated deleted history objects.

Basic Steps for Replicating Deleted Records

You can replicate deleted records using these basic steps for each object.

1. Optionally, determine whether the structure of the object has changed since the last replication request, as described in Checking for Structural Changes in the Object.
2. Call getDeleted(), passing in the object and the relevant time span for deleted records.
3. In the DeleteResult object, iterate through the returned array of DeletedRecord objects containing the ID of each deleted record and the date on which it was deleted (Coordinated Universal Time (UTC) time zone).
4. Take the appropriate action on the local data to remove the deleted records or flag it as deleted.
5. Optionally, save the request time span for future reference, using the value of latestDateCovered.

A client application likely performs other tasks associated with data replication operations. For example, if an opportunity is closed, a client application then runs a new revenue report. Similarly, if a task is completed, the process logs the task in another system.

Sample Code—Java

This sample calls getDeleted() to get all accounts that were deleted in the last 60 minutes. It then writes the ID and the deleted date of each returned account to the console.

public void getDeletedRecords() {
   try {
      GregorianCalendar endTime = (GregorianCalendar)
         connection.getServerTimestamp().getTimestamp();
      GregorianCalendar startTime = (GregorianCalendar) endTime.clone();         
      // Subtract 60 minutes from the server time so that we have
      // a valid time frame.
      startTime.add(GregorianCalendar.MINUTE, -60);
      System.out.println("Checking deletes at or after: "
            + startTime.getTime().toString());
      
      // Get records deleted during the specified time frame.
      GetDeletedResult gdResult = connection.getDeleted("Account",
            startTime, endTime);
      
      // Check the number of records contained in the results,
      // to check if something was deleted in the 60 minute span.
      DeletedRecord[] deletedRecords = gdResult.getDeletedRecords();
      if (deletedRecords != null && deletedRecords.length > 0) {
         for (int i = 0; i < deletedRecords.length; i++) {
            DeletedRecord dr = deletedRecords[i];
            System.out.println(dr.getId() + " was deleted on "
                  + dr.getDeletedDate().getTime().toString());
         }
      } else {
         System.out.println("No deletions of Account records in "
               + "the last 60 minutes.");
      }
   } catch (ConnectionException ce) {
      ce.printStackTrace();
   }
}

Sample Code—C#

This sample calls getDeleted() to get all accounts that were deleted in the last 60 minutes. It then writes the ID and the deleted date of each returned account to the console.

public void getDeletedRecords()
{
   try
   {
      DateTime endTime = binding.getServerTimestamp().timestamp;
      // Subtract 60 minutes from the server time so that we have
      // a valid time frame.
      DateTime startTime = endTime.AddMinutes(-60);
      Console.WriteLine("Checking deletes at or after: "
            + startTime.ToLocalTime().ToString());

      // Get records deleted during the specified time frame.
      GetDeletedResult gdResult = binding.getDeleted("Account",
            startTime, endTime);

      // Check the number of records contained in the results,
      // to check if something was deleted in the 60 minute span.
      DeletedRecord[] deletedRecords = gdResult.deletedRecords;
      if (deletedRecords != null && deletedRecords.Length > 0)
      {
         for (int i = 0; i < deletedRecords.Length; i++)
         {
            DeletedRecord dr = deletedRecords[i];
            Console.WriteLine(dr.id + " was deleted on "
                  + dr.deletedDate.ToLocalTime().ToString());
         }
      }
      else
      {
         Console.WriteLine("No deletions of Account records in "
               + "the last 60 minutes.");
      }
   }
   catch (SoapException e)
   {
      Console.WriteLine("An unexpected error has occurred: " +
                                 e.Message + "\n" + e.StackTrace);
   }
}

Arguments

Limits

When a getDeleted() call returns too many results, the exception EXCEEDED_ID_LIMIT is returned in the response. See API Call Limits for the number of records that can be returned.

Response

GetDeletedResult

Faults

InvalidSObjectFault

UnexpectedErrorFault