Skip to content

Defining Offline Settings for Applications

Define offline settings for the selected application. Offline support enables client applications to access back-end data without a connection. When offline, applications access data from an offline store on the client. SAP Mobile Services moves data between the back end and the client offline store.

The destination settings determine how SAP Mobile Services creates the initial offline store on the client, and how it processes requests for updates from the back end. Define offline back-end connection settings for an application by importing a configuration (.ini) file that has been prepared by a developer. To adjust any settings, you can use the built-in editor to change the properties accordingly at runtime. Be sure to confer with the application developer before making any changes, since changes can impact the mobile application significantly.

See these sections in the Native OData App Development and SAP Business Technology Platform SDK documentation:

To define settings:

  1. In SAP mobile service cockpit, select Mobile Applications > Native/MDK.

  2. Select an application, then select Mobile Offline Access under Assigned Features.

  3. Select Configuration to see a list of configured destinations.

  4. To import an offline configuration, select the upload icon, browse and select a configuration file.

    Note

    Only .ini files can be imported. When you import settings, the state of the offline configuration changes to Configured.

    For information about Application Configuration files, see:

  5. Select the Offline Policies tab to set incoming request throttling threshold and offline store upload policies for the application.

    1. Under Throttling Policy, select Enable Throttling to set throttling policy. Once the policy is enabled, you can control the activity level for the application. Set thresholds for throttling activity once thresholds are reached.

      For Incoming Request Throttling Threshold, configure the request throttling threshold, from 1 to 200 requests. The default value is 200 requests per second. When the offline service reaches the threshold value, no additional requests are handled.

    2. Under Offline Store Upload Policy, select Enable Offline Store Upload to set offline store upload policies. Once the policy is enabled, the device user can upload the local offline store files to the server for the developer to analyze or troubleshoot, subject to the upload policy settings. Specify policy properties.

      Offline Store Upload Policy Properties

      Property Default Description
      Delete Offline Store After 7 days The time to elapse before the offline store files are deleted automatically. This security measure protects the device user, but be sure to allow enough time for the developer to perform the troubleshooting or analysis. The maximum value is 30 days. For legacy configuration values that are more than 30, the value is changed to 30 automatically.
      Maximum Offline Store Size 32 MB The maximum size allowed for the offline store files.

  6. Select the Offline Stores tab to view the uploaded offline stores.

    You see the list of existing offline stores that are available in offline settings. You can also view the Unique ID, Device ID, Created By, File Size, Creation Data, and the Actions you can perform for each offline store. You cannot modify these values, but they are useful for finding and sorting offline stores.

    Offline Stores

    Properties Descriptions
    Unique ID The unique identifier for the offline store.
    Device ID The device identifier associated with the offline store.
    Name The offline store name.
    Note Text notes about the offline store, up to 120 characters.
    By Creator of the offline store.
    File Size (KB) The current offline file size in KB.
    Creation Date (UTC+0800) The offline store creation date in UTC format.
    Actions Actions that can be taken, such as deleting the offline store.

  7. To download an existing offline store, click the download icon.

  8. To delete an existing offline store, select the corresponding check box, and click the delete icon.

  9. Select Save.

  10. Select Info to see feature details, such as useful URLs.

Editing the Application Configuration File

Use the Offline editor to make updates to the application configuration file. You can view base endpoint properties for the selected offline application, and set some custom parameters in the application configuration file using SAP mobile service cockpit.

An example of a custom parameter is to disable CSRF for the development and test environment, using the disable_fetch_csrf_token_request property described in step 5. Create a key-value pair using Y to disable CSRF Token protection. This is not supported in a production system because of security reasons, but is useful in a QA, development, or test system.

Another example of a custom parameter is to enter before and after defining requests at the end-point level, using the before_function and after_function properties described in step 5. The offline service sends separate requests to the back-end server based on this configuration.

To learn more, see Application Configuration File (iOS) and Defining an Application Configuration File (Android).

  1. In SAP mobile service cockpit, select Mobile Applications > Native/MDK.

  2. Select an application, then select Mobile Offline Access under Assigned Features (or add it first).

    On the Configuration tab, any offline data store destinations are listed.

    Destination Properties

    Property Description
    Destination The offline client endpoint destination, such as com.<domain>edm.sampleservice.v2.
    State The current state of the destination, such as No Custom Settings or Configured.
    Action The action to take such as Create, Edit or Delete.

  3. Select the create icon.

  4. Specify endpoint properties, and click Next.

    Endpoint Properties

    Property Description
    Destination Name (Display only) The destination name cannot be modified.
    Prepopulates Offline Data Whether to populate offline data on the client in advance. Select Yes, No or Shared-only. If you select No, then in the analytics chart, the average initial download time will be less than the average refresh download time.
    Data Refresh Interval How often to refresh the data on the client when online, in minutes.
    Service Document Format The acceptable service document format to use for the OData back-end server. You can enter a customized value as a string, such as application/name, or you can select application/atomsvc+xml, application/xml or application/json.
    OData Communication Format The format used, such as application/json;q=1,application/atom+xml;q=0.5.
    Delta Communication Format A subset of the OData communication format, such as application/atom+xml.
    Database Collation Character set for database collation, such as UTF8BIN.
    Database Case Sensitivity Whether database case matters; select to enable case sensitivity.
    JSON Date Time Offset The date-time offset format, such as UTC or Defined by Offset Portion.
    Local Data Expiration How long to keep local data before it expires, in hours.
    Allow Omitting Max Length Whether to limit the maximum length of an entry; select to impose no maximum length.
    Content ID Header Location Content identifier header, such as Mime or Operation.
    Number of Max Delta Resends The maximum number of times changes can be sent, such as 5.
    Batch All Defining Requests Whether to batch all requests when online.
    Delta Tracking Whether to track changes. Specify Auto, Always, or Never.
    Download Threads Enables you to download offline data using multiple treads. This can speed up download for large datasets. Set between 1-3. Multi-thread upload is enabled if the value is bigger than 1. Leave blank or set to 0 if multiple threads are not used. See Configuring Offline Multi-thread Sync for information.
    Full Download if Metadata Changes Specify whether to download the full OData offline schema to the device on sync if the metadata changes. The parameter is enabled by default, meaning if you sync from the device, the full database is downloaded. Remove the check mark to disable the feature, meaning if you sync from the device, only changes are downloaded to the device.

  5. In Endpoint Customized Properties, click add to add private parameters, and then click Next.

    Create key-value pairs for the parameters.

    Endpoint Customized Properties

    Property Description
    Key The key, such as disable_fetch_csrf_token_request.
    Value Its value, such as Y.
    Action The action to take, such as Create or Delete.

    For example:

    • check_repeatable_requests ‒ enter Y to check requests.

    • disable_fetch_csrf_token_request ‒ enter Y to disable token requests.

    • force_medialink_absolute_url ‒ enter Y to enforce absolute URLs.

    • skip_nullable_relationship_check ‒ enter Y to skip relationship checks.

    • throttling_threshold_initial_download ‒ enter a value to establish the threshold for throttling initial download, such as 11.

    • throttling_threshold_upload ‒ enter a value to establish the threshold for throttling upload, such as 22

    • throttling_threshold_delta_download ‒ enter a value to establish the threshold for throttling delta download, such as 33.

    • media_link_prefix ‒ enter a prefix to use for media links, such as test2.

    • generate_implicit_entity_id_in_response ‒ enter Y to generate an entity ID.

    • disable_fetch_csrf_token_request ‒ enter Y to disable CSRF token protection. This is not supported in a production system because of security reasons, but is useful in a QA, development, or test system.

    • service_document_format ‒ enter the service document format as a string, such as application/json or application/xml.

    • before_function and after_function ‒ enter before and after function to defining requests at the end-point level. The offline service sends separate requests to the back-end server based on this configuration. Sample key-value pair entries:

      before_function=GetProductsByRating?rating=3

      after_function=GetProductsByRating?rating=4

    • log_request_headers_when_bad_request ‒ indicates whether to log request headers. The default is N. When set to Y, mobile services logs the request headers when meeting bad requests.

    • early_populate_backend_generated_values ‒ indicate whether missing values can be populated from the back-end server during upload, if available. Currently, this feature only supports entity creation and does not support entity patching or updating. The default is N.

      If this option is set to Y, the server populates the back-end generated properties to the client immediately after upload (for example, if a primary property is maintained by the back end and the client creates an entity without a primary key).

      When this option is N, after uploading the new entity, missing values remain empty (for example, the primary property of the local entity remains empty and must be populated manually in the next download). But, when this option is set to Y, after uploading the new entity, the primary property of the local entity will also be updated.

      This feature does not change the pending state of the local entity. The pending state and the request in the request queue are only removed after download. Note that turning this option on might have an effect on upload performance.

    • add_csrf_token_header_for_get_request ‒ enables you to add X-CSRF-Token headers to GET requests. Its value can be Y or N (the default is N). When set to Y, mobile services adds a X-CSRF-Token header to the GET requests sent to the back-end server; if set to N, no X-CSRF-Token header is added to GET requests.

    • disable_normalize_time ‒ enables mobile services to keep the original values of Edm.Time type attributes that are sent from the back-end server instead of normalizing them. Enter Y or N (the default).

      When set to N, mobile services normalizes the values. For example, if the value of an Edm.Time type attribute is PT01D08M20S, mobile services normalizes it to PT1D8M20S and saves it to a varchar type, so it affects the column sort. When set to Y, mobile services retains the original values from the back-end server, without normalization.

    • v2_use_post_http_method_for_patch ‒ enables you to disable the POST HTTP tunneling method for OData (Version 2 only).

  6. In Client Indexes, click add to add the client index parameters, and then click Next.

    Client Index Properties

    Property Description
    Index The client index name.
    Properties The client index properties.
    Action The action to take, such as Delete.

  7. In Defining Requests, click add to add the defining request parameters, and then click Next.

    Request Properties

    Property Description
    Name The defining request name.
    Refresh Interval (min) The interval time, in minutes, between downloads of the shared data.
    Delta Tracking Specify how to track OData deltas: Auto, Always, or Never. Delta tracking can improve performance on the client.
    Token Lifetime (min) The time, in minutes, until the OData delta token expires. While valid, only changed data is downloaded to the offline store. When the delta token expires, the entire data set is replaced.
    OData Communication Format Specify the format to use for OData payload non-delta requests at the defining query level. For example, some back ends such as Gateway require that you use XML and not JSON. With this property you can configure an efficient defining query with a JSON content type. You can select one of the predefined query options: application/atom+xml, or application/json. Or you can write your own. Be sure to set a value if you write your own, or it will be left empty. If no configuration is provided, the destination level configuration is used.
    Delta Communication Format Specify the format to use for OData payload delta requests at the defining query level. For example, some back ends such as Gateway require that you use XML and not JSON. With this property you can configure an efficient defining query with a JSON content type, even if you're using a Gateway back end without delta support. You can also configure a Gateway back end with delta support using XML. You can select one of the predefined query options: application/atom+xml, or application/json. Or you can write your own. Be sure to set a value if you write your own, or it will be left empty. If no configuration is provided, the destination level configuration is used.
    Share Data Whether data is shared among different clients or users.
    Download Order If you enabled multiple thread download in step 4, you can assign a number to each defining request to indicate the order each request should be processed. Lower numbers are processed before higher numbers. For example, if you assign 66 to one request and 777 to another, 66 will be processed before 777. See Configuring Offline Multi-thread Sync for information.
    Action The action to take, such as Delete.

  8. In Defining Request Groups, click add to add the defining request group parameters, and click Finish.

    Request Group Properties

    Property Description
    Request Names Select one or more defining requests.
    Action The action to take, such as Delete.

Configuring Offline Multi-Thread Sync

You can configure multiple back-end threads in SAP mobile service cockpit for offline synchronization. This gives you more control over synchronization, leading to better sync performance, especially for large data sets. The application must support multiple-thread sync in the imported offline configuration file (.ini), and the feature must be enabled for the tenant and its customers.

Once you upload the offline configuration file (.ini), configure the application to download offline data using multiple treads. First, enable Download Threads for the application, and then assign a Download Order value to each defining request. The download requests are processed in phases, from the lowest value first, to the highest value. For example, a value of 66 is processed before 777. Each phase must be completed before the next phase starts.

Note that requests in the same download phase are downloaded in parallel, with no guaranty for the download order of the requests within the phase. For example, requests in download phase 66 are all handled in parallel. If download order matters, specify a different download phase for them.

  1. In SAP mobile service cockpit, select Mobile Applications > Native/MDK.

  2. Select an application, then select Mobile Offline Access under Assigned Features (or add it first).

  3. On the Configuration tab, create or edit an offline configuration, using information in Editing the Application Configuration File for entries.

    In the Offline Configuration wizard, the Endpoint Info page, make an entry in Download Threads to enable multi-thread synchronization. You can enter 1, 2, or 3 for download threads. Multi-thread download is enabled if the value is larger than 1. If you leave the field blank or enter 1, multi-thread sync is not enabled. Select Next to proceed.

  4. In Define Request, make an entry in Download Order for each defining request to indicate the order the request should be processed. Lower numbers are processed before higher numbers. For example, if you assign 66 to one request and 777 to another, 66 will be processed before 777. Select Next to proceed.

  5. When you are finished with these entries, select Finish to save. The offline configuration is updated. The next offline synchronization will be processed in the order you specified.

Defining Network Synchronization

Define the policy for synchronizing application components on various channels, including WiFi, mobile networks, and roaming. The developer must include a user interface on the client app for users to configure when to synchronize large data uploads. This feature is available only for apps created with SAP BTP SDK for iOS and SAP BTP SDK for Android.

This feature lets administrators control synchronization behavior for each app from the cockpit, by indicating when it is okay for data-heavy SDK components to synchronize. Eligible components include:

  • Analytics
  • Client resources
  • Logs
  • Offline OData

To define the network synchronization policy:

  1. In SAP mobile service cockpit, select Mobile Applications > Native/MDK or SAP Mobile Cards.

  2. Select an application, then select Mobile Settings Exchange under Assigned Features.

  3. Under Network Synchronization Policy, select Enable Network Policy.

  4. For each component in the list, select each network channel to use for synchronizing data.

    Network Synchronization Policy

    Policy Description
    Component The component that's impacted by the network synchronization policy (such as Analytics, Client Resources, Logs, and Offline OData).
    WiFi Indicates whether synchronization should automatically occur over WiFi.
    Mobile Networks Indicates whether synchronization should automatically occur over mobile networks. Network provider charges may apply.
    Roaming (Android only) Indicates whether synchronization should automatically occur while roaming. Network provider charges may apply.

  5. Select Save.

Enabling Shared Devices

(Native SDK only) For environments where employees share devices, you can enable the uploading of pending changes from previous device users. This is useful in case employees forget or are unable to upload their work.

This feature is intended for environments where devices are shared, such as when employees share devices over multiple work shifts. The upload can be executed in the back end, and the next employee can continue work the next day. The feature ensures security, so that users only receive their own messages, not messages intended for a previous user. The feature must be enabled for the application.

  1. In SAP mobile service cockpit, select Mobile Applications > Native/MDK.

  2. Select an application, then select Mobile Settings Exchange under Assigned Features.

  3. Under Shared Devices, select Allow Upload of Pending Changes from Previous User. When you enable this feature, you also enable multiple user mode for the client via the QR code.

  4. Select Save.

Last update: May 18, 2022