Developer

Additional Best Practices for Defining Requests and Offline OData Store Provisioning

Describes additional best practices to consider when developing an offline app.

For the purposes of this document, Offline OData Service refers to the component in either SAP Mobile Platform Server or mobile service for development and operations that moves data between the back-end (OData Producer) and the client offline store.

Best Practices for Defining Requests

  • Using “/CollectionA” and “CollectionB” versus “/CollectionA?$expand=CollectionB”

    This depends on the OData Producer and the data in those collections. A defining request with an $expand can only be broken up into multiple defining requests without $expand if the associations in the $metadata defines referential constraints.

    It is generally preferable to use $expand in OData queries for relationships, but this may not always provide the best performance for offline OData:
    • Lack of support for deltas with $expand - OData Producer deltas for defining requests with expands are not supported by the Offline OData Service directly. If a defining request contains an $expand there are two possibilities, with respect to deltas:
      1. The Offline OData delta computation is used
      2. If the Offline OData delta computation is disabled, a full download of the data occurs
    • Data duplication - sometimes an app requires more than one defining request to get all the data and relationships because their data does not form a tree rooted from a single set. In such a case, many defining requests may have to expand to the same sets, creating duplicate entities that are retrieved from the OData Producer. Splitting the defining requests up resolves this problem because each entity is downloaded only once, and the Offline OData Service computes the relationships using the referential constraints.
    • Shared data - you may have a set of data that is shared by all users but is referenced by user specific data. In this case, you want to separate the shared data into a separate request from the user specific data. The relationships between the shared data and the user defined data are computed by the Offline OData Service using the referential constraint properties, but the shared data needs to be downloaded only once for all users, instead of for each user.

Provisioning the Device

  • $top and $skip

    Customers should not use $top or $skip in their defining requests. The amount of data retrieved from the OData Producer should be controlled using $filter queries or other back-end specific means (such as based on the currently authenticated user). If the use of $top and $skip is intended to break up how much data the OData Producer can send at one time, then the service should be changed to use server driven paging instead (IE. return next links). The customer is free to use $top and $skip when executing local queries.

  • Multiple stores

    A developer can use multiple stores. A store can only be used for one service, and it is a best practice that only one store is used per service.

  • Errors
    The errors reported on the client are likely either:
    • Communication errors problems connecting and communicating with the server.
    • Back-end errors errors while the server is communicating with the OData Producer back-end or preparing the database for the client. Typically back-end errors result in a generic error message on the client (for now) and require the developer to look at the SAP Mobile Platform Server log to diagnose. Back-end errors are typically caused by incorrect user input (for example, incorrect defining requests) or communication problems with the OData Offline Server (it has gone down or the back-end configuration in the SAP Mobile Platform Server is wrong). Regardless of the type of error during the initial refresh of data (retrieving the database for the first time), the offline store automatically cleans up the erroneous state/data, allowing the developer to start over.