Offline applications should be designed with ability to handle any errors and conflicts.
Offline OData Errors¶
Offline OData errors generally fall into the following categories:
Occur when communication with the server is interrupted during an upload or a download operation.
You can generally resolve network errors by retrying the operation at a later time. However, if network errors occur due to server-side application configuration, ensure that you have specified the correct settings.
Contract Violation Errors¶
Occur when the application attempts to perform an invalid operation, such as sending a malformed request or attempting to call API methods without first opening the offline store. Such operations will be rejected by offline store, therefore the offline store won’t be impacted, but the application should handle the operations in a way that they can be corrected.
Business Logic Failures¶
Occur if business logic at the OData service prevents a change that is allowed at the offline store. The error is recorded in
ErrorArchive, an Offline OData specific entity set containing detailed information about errors. The application can obtain the body of the original request from
Offline OData Conflicts¶
Conflicts are specific types of errors that arise when multiple clients simultaneously modify the same data in the back end. An offline application should include a process to either avoid conflicts, or logs and resolves them when they arise.
OData services use
ETags to identify conflicts. An
ETag is an identifier that is assigned to a specific version of an entity. When an entity is modified, a new
ETag is assigned.
ETags to detect conflicts in your application:
The application retrieves an entity, along with its
ETag, from the offline store.
When an update request is made, the application sends the request, along with the original
ETag, to the offline store.
ETagthat is provided with the update request matches what is currently in the offline store, the update is performed locally and a new
ETagis generated. The request and the
ETagare added to the request queue. If the
ETagdoes not match, an error is generated.
When an upload is performed, the request and the
ETagare sent to the OData service. If the
ETagmatches the one in the OData service, the update is performed and the updated entity plus a new
ETagETag are retrieved by the application during the next download. If the
ETagdoes not match, the request fails, the error is put in
ErrorArchive, and the application then determines how to proceed.
Usually when an update results in an
ETag conflict, the offline store may need to present the latest state from the back end with the modified state so that the application can decide whether additional changes are necessary. A download, possibly with a limited set of defining queries, might need to be done. When the download completes, the offline store will have the latest
ETag and data. From the offline store, the application can only see the latest state from the back end with the associated pending requests applied. If you require the latest state from the back end for proper handling of the conflict, you can choose to remove entries in
ErrorArchive. This results in removal of all requests in error as well and associated entities returning to server state. This is described further in Handling Failed Requests.