getUpdated()

Retrieves the list of individual objects that have been updated (added or changed) within the given timespan for the specified object.

Syntax

GetUpdatedResult[] = sfdc.getUpdated(string sObjectType dateTime startDate dateTime EndDate);

Usage

Use getUpdated() for data replication applications to retrieve a set of IDs for objects of the specified object that have been created or updated within the specified timespan. The getUpdated() call retrieves an array of GetUpdatedResult objects containing the ID of each created or updated object and the date/time (Coordinated Universal Time (UTC) time zone) on which it was created or updated, respectively. Be sure to read Data Replication before using getUpdated() in your client application.

Note

The getUpdated() call retrieves the IDs only for objects to which the logged-in user has access.

Rules and Guidelines

When replicating created and updated objects, consider the following rules and guidelines:

The specified startDate must chronologically precede the specified endDate value. The specified startDate cannot be the same value as, or later than, the specified endDate value. Otherwise, the API returns an INVALID_REPLICATION_DATE error.
Results are returned for no more than 30 days previous to the day the call is executed.
Client applications typically poll for changed data periodically. For important polling considerations, see Polling for Changes.
Your client application can replicate any objects to which it has sufficient permissions. For example, to replicate all data for your organization, your client application must be logged in with “View All Data” access rights to the specified object. Similarly, the objects must be within your sharing rules. For more information, see Factors that Affect Data Access.
Certain objects cannot be replicated via the API. To replicate an object via the getUpdated() 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.
Certain objects cannot be deleted, such as Group, User, Contract, or Product2 objects. However, if instances of these objects are no longer visible in the Salesforce user interface, they may have been rendered inactive so that only users with administrative access can see them. To determine whether a missing object instance has been made inactive, your client application can call getUpdated() and check the object’s active flag.
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.

Basic Steps for Replicating Updated Objects

Replicating objects involves the following basic steps for each object that you want to replicate:

Optionally, the client application determines whether the structure of the object has changed since the last replication request, as described in Checking for Structural Changes in the Object.
Call getUpdated(), passing in the object and timespan for which to retrieve data.
Iterate through the returned array of IDs. For each ID element in the array, call retrieve() to obtain the latest information you want from the associated object. Your client application must then take the appropriate action on the local data, such as inserting new rows or updating existing ones with the latest information.
Optionally, the client application saves the request timestamp for future reference.

A client application likely performs other tasks associated with data replication operations. For example, if an opportunity were to become closed, a client application might run a new revenue report. Similarly, if a task were completed, the process might log this somehow in another system.

Sample Code—Java

private void getUpdatedSample() {
  try {
    //  You can use the server timestamp as known point in time
    Calendar serverTime = binding.getServerTimestamp().getTimestamp();
    //    Create a start time value for the call
    GregorianCalendar startTime = (GregorianCalendar) serverTime.clone();
    //    Create an end time value for the call
    GregorianCalendar endTime = (GregorianCalendar) serverTime;
    //    subtract 5 mins from the server time so
    //    that we have a valid time frame, you can use just
    //    about any timespan you want, 5 minutes is arbitrary
    startTime.add(GregorianCalendar.MINUTE, -5);
    System.out.println("Checking updates at: " + startTime.getTime().toString());
    GetUpdatedResult ur = binding.getUpdated("Account", startTime, endTime);
    //   Check the length of the returned array of IDs
    //    to detect if you got any hits
    if (ur.getIds() != null && ur.getIds().length > 0) {
      for (int i=0;i<ur.getIds().length;i++) {
        System.out.println(ur.getIds(i) + " was updated between " 
                           + startTime.getTime().toString() + " and " 
                           + endTime.getTime().toString());
      }
    } else {
      System.out.println("No updates to accounts in the last 5 minutes.");
    }
  } catch (Exception ex) {
    System.out.println("\nException caught, error message was: \n" + ex.getMessage());
  }
}

Sample Code—C#

private void getUpdatedSample() 
{
    DateTime endTime = binding.getServerTimestamp().timestamp;
    DateTime startTime = endTime.Subtract(new System.TimeSpan(0, 0, 5, 0, 0));
    sforce.GetUpdatedResult gur = binding.getUpdated("Account", startTime, endTime);
    if (gur.ids.Length> 0) 
    {
        for (int i=0;i<gur.ids.Length;i++) 
        {
            Console.WriteLine(gur.ids[i] + " was updated between " + startTime.ToString()
                               + " and " + endTime.ToString());
        }    
    } 
    else 
    {
        Console.WriteLine("No updates to accounts between " + startTime.ToString() + 
                           " and " + endTime.ToString() );
    }
}

Arguments

Name	Type	Description
sObjectTypeEntityType	string	Object type. The specified value must be a valid object for your organization. For a list of standard objects, see Standard Objects.
startDate	dateTime	Starting date/time (Coordinated Universal Time (UTC) time zone—not local— timezone) of the timespan for which to retrieve the data. The API ignores the seconds portion of the specified dateTime value (for example, 12:30:15 is interpreted as 12:30:00 UTC).
endDate	dateTime	Ending date/time (Coordinated Universal Time (UTC) time zone—not local— timezone) of the timespan for which to retrieve the data. The API ignores the seconds portion of the specified dateTime value (for example, 12:35:15 is interpreted as 12:35:00 UTC).

Note

There is a limit of 200,000 IDs in the result GetUpdatedResult[]. If your getUpdated() call returns more than 200,000 IDs, an exception EXCEEDED_ID_LIMIT is returned. You can correct the error by choosing start and end dates that are closer together.

Response

GetUpdatedResult[]

Faults

InvalidSObjectFault

UnexpectedErrorFault