Skip to content

Finding Entities in Error State

Any entities or relationships in the offline store that were affected by a failed request are moved into error state, which indicates that the state of the entities or relationships in question may not be valid and should be fixed before proceeding.

Entities that are in error state are identified by presence of the inErrorState annotation. If the failing request had the effect of deleting an entity or relationship, these deleted items will reappear in the offline store and contain the additional isDeleteError annotation.

There are two approaches to locate entities that are in error state.

Note

You cannot currently locate relationships that are in error state.

The first approach is through filtering based on the error state setting in entities.

// Count the number of events in error state
DataQuery query = new DataQuery().from(EventServiceMetadata.EntitySets.events)
            .filter(OfflineODataQueryFunction.inErrorState()).count();
long errorCount = eventService.executeQuery(query).getCount();

// Get event(s) in error state
query = new DataQuery().filter(OfflineODataQueryFunction.inErrorState());
List<Event> eventsInError = eventService.getEvents(query);
/// Count the number of events in error state
var query = DataQuery().from(EventServiceMetadata.EntitySets.events)
        .filter(OfflineQueryFunction.inErrorState())
let errorCount = try service.executeQuery(queryErrorCount).count()

/// Get event(s) in error state
query = DataQuery().filter(OfflineQueryFunction.inErrorState())
let eventsInError = eventService.fetchEvents(matching: query)

The second approach is by locating the entity that is in error state due to the failure of the request from ErrorArchive.

// The navigation property AffectEntity can be used to locate the entity
// affected by this error. In other words, the entity that the
// the OData request affected.

// Retrieve an error from the ErrorArchive
EntityValue error = ...;

// Load the navigation property for a particular error from the ErrorArchive
eventService.loadProperty(affectedEntityProp, error, null);

// Get the affected entity
EntityValue entity = affectedEntityProp.getEntity(error);
if (entity instance of Event) {
    // Cast the EntityValue instance to the generated proxy class
    Event eventInError = (Event) entity;

    // Handle the event
    ...
}
/// The navigation property AffectEntity can be used to locate the entity
/// affected by this error. In other words, the entity that
/// the OData request affected. See the code sample in topic
/// [ErrorArchive Entity Properties](ErrorArchive_Entity_Properties.md)
/// for details of retrieving errors from ErrorArchive.
let error = ...

/// Load the navigation property for a particular error
try eventService.loadProperty(affectedEntityProp, into: error)

/// Get the affected entity
let entity = affectedEntityProp.entityValue(from: error)
if let event = entity as? Event {
    // Handle the event
    ...
}

See the code sample at the bottom of the topic Handling Errors and Conflicts for more details about retrieving errors from the ErrorArchive.

There is a current limitation that only one entity is referenced by the AffectedEntity navigation property. In the case of a relationship operation, two entities are affected but only one (from) can be reached by the navigation property. The other entity (to) can be located using one or more of the following steps:

  1. Examine the error message from the OData service in the ErrorArchive entry to determine the type of relationship operation and the entity type of the other end.
  2. Examine the RequestBody property of the ErrorArchive entry to determine the key of the entity of the other end.

Last update: April 14, 2021