Initialization and Synchronization¶
Offline OData Initialization¶
Before you can use an OData service in your Mobile Development Kit app, you must first initialize it. Use the OData Service Initialize action to initialize your OData service.
For an offline-enabled OData service, you must also specify the defining requests in the
When you execute initialization of an offline OData service for the first time, the offline module will connect and download data from your OData service based on the specified defining requests. The downloaded data will be stored in an offline store and, in subsequent initializations, the offline module will open the offline store.
You can also configure the OData endpoint for each offline OData service using the offline application configuration file in the SAP Mobile Services cockpit. See Application Configuration File for more information.
A defining request is a read query that targets the OData service associated with the offline store and retrieves a subset of the endpoint data. You can define multiple defining requests for each endpoint.
Defining requests retrieve data from the OData service that is sent to the client, either during initialization of the offline store or during a download.
Each defining request consists of a
AutomaticallyRetrieveStream. For more details see Defining Request
You can learn more about defining requests in Defining Queries.
You can customize the offline OData initialization progress text by modifying the
Progress text is customizable text for each state that replaces the progress indicator text shown during the initialization of offline OData.
Offline OData Synchronization¶
Any changes you make using OData actions against this OData service will be performed on the offline store. The changes will remain in the queue in the offline store until you sync your changes back to your back-end OData service.
To update your offline store with changes from your back-end OData service, execute the Offline OData Download action.
Offline OData Upload¶
You can make changes to the local offline store with OData actions referencing the respective OData service. The changes you make will be reflected in the offline store and are stored in a local request queue.
To push your pending changes from the offline store to your back-end OData service, perform an Offline OData Upload action when the device is online. This sends all pending requests in the local request queue to the back-end OData service.
Offline OData upload will only be treated as failed if there are communication errors during the upload operations. The upload is treated as successfully completed if there aren't any communication errors, even if some requests fail due to the back end. See error categories for more information. To determine if any requests have failed, you can examine the
Local entities in the offline store are not updated when an upload is performed, and you can perform multiple upload actions without performing a download. It is good practice (although not required) to perform an upload before you perform a download to make sure that local changes are pushed to the back end.
When performing an OData action that results in changes to the local OData service (that will then need to be synced to the back-end OData service), you can specify
RequestOptions > UploadCategory, which allows you to assign an upload category to the executed request.
When you perform an Offline OData upload action, you can selectively perform upload on certain requests by specifying the
UploadCategories property, which accepts an array of string values. These values represent the upload category names that you have specified in each of the OData actions that you have executed.
UploadCategories is set in an upload action, only requests with the specified upload category will be uploaded to the back end.
Offline OData Download¶
The offline store is updated with the latest data from the back end when the device is online by performing an Offline OData Download action. The timing of performing a download is at the discretion of the application developer. For example, all of these scenarios can be considered, depending on the application:
- Give the user control over the timing of performing the download
- Download at the beginning and end of a day
- Download when the application opens
- Download every 15 minutes
- Download after every upload
Because the download process might run for a long time, you can only invoke it asynchronously and it will usually run in the background.
It is typically recommended to perform an upload before performing a download.
You can cancel an offline OData download (during initialization or download) by triggering the Offline OData Cancel Download action.
You can resume the canceled download by triggering another initialization or download action.