Skip to content

Overview

Offline OData provides flexible mechanisms to help developers handle failed requests.

When a request fails against the back-end OData service during an upload, the request and any relevant details are stored in ErrorArchive. Any subsequent requests that are associated with the same entity are not executed and can also be found in ErrorArchive.

Before utilizing any Offline OData provided support, the developer of an offline application should consider going through the following steps:

  1. Determine which entities will be modified.
  2. Develop appropriate input validation (syntax and business rules) for all involved entity types.
  3. Determine the set of business logic errors that can occur outside the control of the application but is inherent in the way the application functions. For example, updating a purchase order when changes in the back end preclude any modification.
  4. Work with OData service team if possible to define error codes, messages, and so on, that the application can easily parse and take action on. Even if the developer knows the OData protocol well, it may not be easy to determine what the issue is from the information in ErrorArchive. This is especially true for errors that are related to business logic.
  5. If concurrent conflicts can occur with the offline application, determine how to resolve the conflicts by providing appropriate information for end users to resolve the conflicts.
  6. Test as much as possible, including performing on-device testing.
  7. For unknown or unexpected errors, determine the best way to collect information for analysis through appropriate logging, without sensitive data.

Merge Algorithm

Although it is difficult to provide a generic error handling algorithm, Offline OData does provide a heuristic-based merge algorithm that combines new requests as far forward as possible to replace any incorrect data in the original requests with correct data.

Common merge scenarios include the following:

  • Fixing Entity Properties in a Failed POST Request A subsequent PATCH request can be made to the entity (that failed to be created in the back end) with the corrected values. The merge algorithm combines the PATCH and POST requests into a single new POST request containing the corrected values.

  • Fixing Entity Properties in a Failed PATCH Request A subsequent PATCH request that includes the correct values can be made to the entity that failed to be updated in the back end. The merge algorithm combines both PATCH requests into a single new PATCH request containing the corrected values.

  • Discarding a Failed POST Request A subsequent DELETE request can be made to the entity. The merge algorithm deletes the original POST request and nothing is sent to the back end.

  • Fixing a PATCH or DELETE Request that Failed Due to a Stale ETag The application can perform a download operation to obtain the latest version of entity data and the latest ETag. If appropriate, use only a subset of the defining queries that includes the entity set of the entity in error. If the failed request is resubmitted without further changes, the merge algorithm replaces the stale ETag in the failed request with the fresh one.

    If application end users must examine the latest data from the OData service to understand what has changed and adjust the current request accordingly, the application needs to revert the error state after saving the existing value of the entity. Once reverted, the offline store has the latest data from the OData service.

    A complication arises when there are other errors in ErrorArchive. All errors must be fixed first, as deleting one entry in ErrorArchive results in all errors being reverted.

  • Fixing a DELETE Request When an entity isn't deleted from the back end because of an incorrect current value for one or more of its properties, you can fix this issue by submitting a PATCH request. The merge algorithm resequences the PATCH request so that it is executed before the DELETE request.

    If a DELETE request results in an error, the only way to revert the error state is by deleting the entry from ErrorArchive. This carries the same complication mentioned in the previous section, that is, fixing other errors in ErrorArchive first.

There are some limitations to handling failed requests.

  • Request Order and Type The requests computed by the merge algorithm may not match the order or type of the failed requests. As a result, any back-end side effects that rely on a certain type or order of requests may be affected.

    The merge algorithm may alter batch change sets. Requests in one change set may be moved out of a change set or into another change set. If the transactional boundaries are important, then do not attempt to fix requests, and revert the error state before applying any new requests to the offline store.

  • Batch Request Deleting from ErrorArchive (to revert the error state) in a batch request is not supported.

    There are a number of reasons for this, but most importantly, an ErrorArchive deletion is not simply deleting a row from a table. It resets all error information in the store, which can have a significant effect on the entire offline store. Other operations should not rely on the success of this ErrorArchive operation to be executed correctly, which is another reason not to use a change set.

Last update: October 30, 2020