Skip to Content
Author's profile photo Sue Berry

What’s New in Offline OData Q2-2018

With the latest releases of SAP Cloud Platform Mobile Services SDK for iOS and SAP Mobile Platform SDK 3.1 now available to customers, Offline OData has new features and capabilities available in both SDKs.  You can take advantage of these new features regardless of whether you are building native or hybrid mobile apps.  In this blog, I’ll go through all the latest features from Offline OData now available.


If you are new to Offline OData, review an Introduction to Offline OData.

Here is a list of the latest features available in all SDKs


  • Repeatable Requests
  • Support for OData producers that do not support bind operations
  • Add defining requests dynamically
  • Cancel, stop and resume data syncs
  • Upload Offline Store to Server



Repeatable Requests

This feature in Offline OData provides support for repeatable requests at the Offline OData server level if the backend doesn’t support repeatable requests.  Developers will be able to configure the Offline OData server so that it provides that support.

When this functionality is active and the client sends the same request (with the same request ID) twice, typically due to a failure to receive the response caused by a network interruption, the Offline OData server will have cached the response it received from the backend OData producer the first time, and will send that response back to the client instead of sending the request for a second time to the backend OData producer.

The Offline OData server can only go so far. If there is a communication failure between the Offline OData server and the backend OData producer, this feature will not be able to address that.  It is preferable to have repeatable requests implemented in the backend OData producer, this feature is intended for those cases where the backend OData producer does not.



Support for OData producers that do not support bind operations

Developers are now able to provide information to Offline OData when the store opens that specifies whether the backend supports bind operations.  If bind operations are supported, the feature behaves as it did previously.  If the backend does not support bind operations, the following happens if the client issues a bind operation:

  • If the bind operation is included in a dependent entity for a relationship that specifies a referential constraint, the bind operation will be replaced by setting the dependent properties directly.
  • If the bind operation is included in a principal entity for a relationship that specifies a referential constraint, the request will be rejected with an error.
  • If the bind operation is included in an entity for a relationship that does not specify a referential constraint, the relationship will be created locally but the bind will be omitted from the request that is sent to the OData backend.



Add Defining Requests Dynamically

Previously, developers only had the ability to use a predefined list of static dynamic requests for Offline applications.  This limits the types of applications developers can build.

Now, developers can add new defining requests dynamically. In the example below, which uses the ilodata diagnostic tool, we add a defining request for SalesOrderHeaders to a store which has already been opened.  The data from the newly added entity set can now be downloaded and viewed.

ILOData > add defining query
> Enter the defining query name: Sales
> Enter the defining query: SalesOrderHeaders
> Retrieve media streams (Y|N)?: n
The defining query was added successfully.

ILOData > download
Downloading… Sent 611 bytes. Received 2274 bytes.
Download complete.



If we also added a defining request for CustomerDetails, we can view the relationship data between Sales Orders and Customers.

ILOData > get SalesOrderHeaders?$expand=CustomerDetails


Below is a view of the data retrieved.  We look at one sales order and can see the customer details within that sales order.


“__metadata”: {
	“uri”: “SalesOrderHeaders(‘50000000103’)”,
	“type”: “ESPM.SalesOrderHeaders”
“SalesOrderId”: “50000000103”,
“CreatedAt”: “\/Date(1500076800000)\/”,
“CurrencyCode”: “EUR”,
“CustomerId”: “1100000323”,
“GrossAmount”: “95,081”,
“CustomerDetails”: {
  “__metadata”: {
	“uri”: “Customers(‘1100000323’)”,
	“type”: “ESPM.Customers”
  “CustomerId”: “1100000323”,
  “City”: “Chuo”,
  “Country”: “JP”,
  “FirstName”: “Kazuo”,
  “HouseNumber”: “3”,
  “LastName”: “Koike”,
  “UpdatedTimestamp”: “\/Date(1524160623921)\/”


This allows the application to, for example, download only the data it needs initially, then download data for subsequent screens in the background, reducing the startup time.



Cancel Sync Process

This feature enables developers to build in the power to cancel a data sync.  The feature provides an API to allow developers to code the application to react to changing network conditions automatically or provide mobile app users the ability to cancel the data sync manually and retry later.  When the application or mobile app user restarts the data sync, it resumes from where it left off rather than starting over.

One important note about canceling and resuming downloads.  The partial download is not committed until it finishes.  If there are 10,000 queries and it only downloads 5,000 and then the download is canceled, the end-user will not be able to see the 5,000 results until the download resumes and completes.

The function call to cancel the data upload is try provider.cancelUpload().

The function call is cancel the data download is try provider.cancelDownload()



Upload Offline Store to Server

Developers are given an API that allow the mobile application to automatically upload its Offline store database files to SAP Cloud Platform Mobile Services or SAP Mobile Platform without the end-user needing to know which files need to be uploaded or where to find them.  These database files can be used to help diagnose issues.

An Offline store consists of two udb files: entity store database file and request queue database file. These files help diagnose issues with Offline OData, specifically it can help SAP diagnose customer issues.

Previously, customers would need to manually extract the files directly from the device, zip them and send them to SAP support.  Now, app developers can call an API from the SDK that sends the files directly to SAP Mobile Platform server or SAP Cloud Platform mobile services.  Once implemented in the application, the end-user can click a button and the files are automatically sent to the appropriate server as a zip file and are ready for download.


In the example and screenshots below, the developer creates a button   that calls the API.  The user receives a popup stating that the offline store has been sent to the server.


There is a new subtab under Registrations and Users called Client Databases where the administrator can view which databases have been uploaded.  Here the admin can download the files and send them to SAP support for diagnostics and debugging.


If the database is encrypted on the device, the end-user can still send the files to the server.  Once the developer/admin has the files, they will need the key to be able to view the data in those files.



Query created or modified entities

Developers can issue a query to get a list of which entities were modified/created during the last download. The query will simply list the entities and not distinguish created vs modified.  The list of entities is available only for the last download and the query list is reset and updated for each data download.

A common use case for this feature is for applications like SAP Asset Manager, custom mobile development kit applications, or other custom application to have the ability to indicate to the end-user when something is new or updated in the application they are viewing. The application can maintain a list by running a query with this filter function.

The call for this feature is get [entitysets]?$filter=sap.upsertedlastdownload()

In the example below, a customer is added to the local client.

ILOData > post Customers City=Redwood Country=US DateofBirth=1982-01-01T00:00:00  FirstName=Sue LastName=Berry
HTTP 201: Created


After the data sync download, run a query to get all content that has been added or modified on the server since the last download.


ILOData > upload
Uploading… Sent 2372 bytes. Received 659 bytes.
Upload complete.

ILOData > download
Downloading… Sent 752 bytes. Received 626 bytes.
Download complete.



Now, in the example below, I run the filter function to see what has changed since the last download. This change could be from the local user or another user sharing the same server.

ILOData > get Customers?$filter=sap.upsertedlastdownload()
HTTP 200: OK

   “d”: {
      “results”: [
           “__metadata”: {
	        “uri”: “Customers(‘2000000001’)”,
	        “type”: “ESPM.Customers”
           “CustomerId”: “2000000001”,
           “City”: “Redwood”,
           “Country”: “US”,
           “DateofBirth”: “\/Date(475286400000)\/”,
           “EmailAddress”: “”,
           “FirstName”: “Sue”,
           “HouseNumber”: null,
           “LastName”: “Berry”,
           “UpdatedTimestamp”: “\/Date(1524161547373)\/”

ILOData >

Assigned Tags

      You must be Logged on to comment or reply to a post.
      Author's profile photo Mike Doyle
      Mike Doyle

      Thanks Sue there are some useful features there. Creating defining requests for stores that are already open will be very handy

      Author's profile photo Michael Healey
      Michael Healey

      Another interesting concept Sue Berry that I look forward to evaluating. I am particularly interested  in the relationship between oData services that have already been optimised for delta updates (server side and agentry framework) through use of delta tokens and the additional offline support available in SCP Mobile Services.

      Is the new capability in SCP MS intended to replace server side oData delta processing?

      Let's see....

      Author's profile photo Luke Phelan
      Luke Phelan

      Thanks Sue,

      The requirement to cancel sync has come up recently for me. Is there API documentation that has been updated to include these new functions? I can't seem to find any.

      Author's profile photo Sue Berry
      Sue Berry
      Blog Post Author

      Hi Luke,


      Sorry for the delay in getting back to you.

      I'll check to see if there is something published in the help portal.  If not, I'll try to get you a sample.



      Author's profile photo Sue Berry
      Sue Berry
      Blog Post Author

      Hi Luke,


      i hope this helps. Please note that this is already available with SAP Mobile Platform SDK 3.1.  It will be available in the iOS 2.2 release as well.

      /// Cancels all downloads and file downloads including those that are queued.

      /// This method will also cancel an initial download and file download if it is called while the OfflineODataProvider is opening for the first time.


      /// - throws: `OfflineODataError` if an there are no downloads or file downloads to cancel

      public func cancelDownload() throws -> Void


      /// Cancels the current upload.


      /// - throws: `OfflineODataError` if an there are no uploads to cancel

      public func cancelUpload() throws -> Void


      Author's profile photo Sebastian Rahmann
      Sebastian Rahmann

      Hi Sue,

      first of all thank you for the excellent blog entry. I´d like to ask you for some feature informations about the Kapsel Offline OData Plugin.

      Are there planned implementations for the following features?

      • Consolidated CUD operations (e.g.: Multiple updates for the same entity).
      • Offline draft concept (e.g.: To handle transient data and the moment of the synchronization into the backend systems via the offline store).

      Any information would be appreciated.


      With kind regards,

      Sebastian Rahmann



      Author's profile photo Sue Berry
      Sue Berry
      Blog Post Author

      Hi Sebastian,


      Thank you for the comment and your interest in Offline OData.

      Please email me and I can send you a full Offline OData Roadmap as we are currently working on the features you are requesting.  I cannot provide timelines in the comments, but our roadmap provides some projected timelines (subejct to change) and more details about the feature.

      • Consolidated CUD operations is on our roadmap already listed as transaction merge optimization.
      • Offline draft concept.  More details may be needed here, but if the following features meet your requirements, then it is also on our roadmap to be released at the same time as transaction merge optimization.
        • The ability to remove all requests from the queue that involve creating a new entity and subsequently deleting that same entity prior to uploading
        • The ability to group requests by a user-supplied transaction ID, via custom header, that would then be automatically grouped into as few batches/change sets as possible
        • The ability to merge requests on the client (see above).



      Author's profile photo Mikael Gurenius
      Mikael Gurenius

      Great news! The dynamic defining request is much appreciated!

      When can we expect to remove a defining request? Or at least, be able to choose what defining requests is part of a "download"?

      Imagine an app that progressively load parts of a large data set (like Equipments connected to a geographic region). As the user travels, new data is loaded progressively. Then there is a need to "clean" data not used any more.

      Trying this out in ILOData, a delta-query for each defining request is always sent.

      Author's profile photo Jay Xue
      Jay Xue

      Hi Sue, this is a great article introducing the features!

      Several comments:

      1. In the list of latest features available, "Query Created or Modified Entities" is missing.
      2. In "Add Defining Requests Dynamically", by "static dynamic requests" I think you mean "static defining requests". Also, in the new SDK we adopted the term "defining query", as can be seen in output of ilodata (defining request is the old term). We can use the new term consistently wherever needed.
      3. The function calls for "Cancel Sync Process" are specific to SAP Cloud Platform Mobile Services SDK for iOS. For SAP Mobile Platform SDK 3.1, the calls are different on various platforms. We may want to mention that explicitly.