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 update the offline configuration, you can (1) select the edit button to edit the offline configuration and save it at runtime, or (2) remove the current configuration, update the configuration file, and then import it again. 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:

SAP Mobile Services offline supports key properties that were skipped over or missed when default values were generated by the back-end OData service (Version 4 only), including object entries, and referential constraint definitions that contain partial primary keys. For primary keys that are not referenced by foreign keys, a server-side default value is used. This enables SAP Mobile Services to process Cloud Application Programming (CAP) draft entities for offline. See Understanding Keys for more information.

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. You could further customize by implementing the '{syncType}' parameter in the destination URL to specify different actions for an initial sync and a delta sync.

To learn more, see Application Configuration File (iOS) and 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 add 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 use mobile services to send delta responses to the client even if the back end can’t support delta query. Delta tracking can help to decrease the data transfer size during the sync; in subsequent syncs, mobile services only sends added/updated/deleted data to the client instead of sending all data tracking changes. Options include Auto, Always, or Never. See the Delta Tracking Property Details table below for setting details.
    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.
    URL Rewrite in Offline Service Specify whether to enable URL rewrite for the selected offline application. Your selection sets the no_url_rewrite property. If you select the checkbox (sets the property to true) offline URL rewriting is enabled (default). If you leave the checkbox unselected (sets the property to false) offline URL rewriting is disabled, and the Mobile Connectivity proxy service handles URL rewriting, if it is configured. Note that if you enable URL rewrite in the Mobile Offline service, you must also configure these settings for the Mobile Connectivity destination: (1) set the "Rewrite Mode" attribute to "Rewrite URL", and (2) ensure that the "Relative Rewrite Paths" attribute is empty. See Creating a Destination for information about these attributes.

    Delta Tracking Property Details

    Setting Description
    Auto (default) Indicates that mobile services should determine automatically whether to use the middleware delta tracking that is provided by mobile services, or to use back-end delta tracking: (1) if the back-end server supports delta query, mobile services uses the back-end delta query and does not enable middleware delta tracking; (2) if the back-end server does not support delta query, mobile services enables middleware delta tracking to support delta tracking using mobile services.
    Always Indicates that mobile services should enable middleware delta tracking even if the back-end server supports delta query. This option is not recommended for most scenarios. It should be used only when the back-end server‘s delta query is not very reliable. For example, the back-end server returns the whole data set even when it receives a delta query to only track changes.
    Never Indicates that mobile services should not enable middleware delta tracking. When the server supports delta query, disabling middleware delta tracking can help decrease memory use and database operations, and help improve sync performance. This option is not recommended when the back-end server does not support delta query.
  5. In Endpoint Customized Properties, click add to add private parameters, and then click Next.

    View the list of key-value pairs, and create or edit key-value pairs for the parameters.

    Endpoint Customized Properties

    Property Description
    Key The key, such as disable_fetch_csrf_token_request. Select a key from the list or input a valid key directly. Keys are categorized by type, such as String, Integer, Integer Array, and Boolean. Once you select a key, select the help button for more information, such as Enter Y or N to disable or enable fetching CSRF tokn for requests; if not set the default is N.
    Value The key value, such as Y. The field provides a hint as to the value that is expected.
    Action The action to take, such as Create or Delete.

    Endpoint Customized Property Descriptions

    Key Description Type
    before_function Enter before_function to defining requests at the end-point level; the offline service sends separate requests to the back-end server based on this configuration. Example format: GetProductsByRating?rating=3

    Optionally you can add '{syncType}' as a placeholder to the destination URL:

    Example format: before_function = OpenSyncSession?SAPProductTechName='SAP_SERVICE_ASSET_MANAGER'& SyncType='{syncType}'

    String
    after_function Enter 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. Example format: GetProductsByRating?rating=4

    Optionally you can add '{syncType}' as a placeholder to the destination URL:

    Example format: after_function = CloseSyncSession?SAPProductTechName='SAP_SERVICE_ASSET_MANAGER'& SyncType='{syncType}'

    String
    offline_db_creation_parameters Specifies a list of client database creation options, semicolon separated. Example format: precision=100;scale=10 String
    media_link_prefix Enter a prefix to use for media links. Example format: test2 String
    repeatable_requests_lifetime Controls how long in minutes that repeatable request responses are kept. The default value is 72000 (50 days). Example format: 36000 Integer
    max_length_facet_default Specifies the default MaxLength values in bytes that should be assigned by the system when they are not provided in the OData metadata. If not specified, the default value is 1536. Example format: 2048 Integer
    max_retry_times Enter an integer value between 0 to 10 to establish the maximum number of times SAP Mobile Services should try to connect to the back-end server, when the back-end server cannot be accessed. For example, enter 5 for five retries. The range is 0-10, but a mid-range value is recommended. Example format: 5 Integer
    repeatable_exclude_status Specifies a list of status codes which should not be checked for repeatable requests. Example format: 401, 403 Integer Array
    check_repeatable_requests Enter Y or N to enable or disable checking repeatable requests; if not set the default is N. Boolean
    download_in_order Indicates whether defining queries should be downloaded in the order in which they are defined in the configuration file. If not set the default is N. Boolean
    disable_fetch_csrf_token_request Enter Y or N to disable or enable fetching CSRF token for requests; if not set the default is N. Boolean
    force_medialink_absolute_url Enter Y or N to enable or disable forcing medialink absolute URL; if not set the default is Y. Boolean
    skip_nullablerelationship_check Enter Y or N to enable or disable skipping nullable relationship check; if not set the default is Y. Boolean
    allow_defining_query_removal Enter Y or N to enable or disable defining query removal; if not set the default is N. Boolean
    generate_impicit_entity_id_in_response Enter Y or N to enable or disable generating implicit entity id in response; if not set the default is N. Boolean
    v4_use_post_http_method_for_patch

    v2_use_post_http_method_for_patch
    These options control the HTTP method used by the server to interact with the OData back end to replay a "PATCH" operation. The mechanism is similar to what is described in OData Operations (OData Version 2.0), see Section 3.2, Method Tunneling through POST.

    When the option is set to true, the server sends a POST request with the header "X-HTTP-Method: MERGE". Otherwise, the server sends the "PATCH" directly. How you set these options depends on whether or not the OData back end supports the PATCH method. If not set, the default is used.

    Enter Y or N to enable or disable the POST tunneling method for OData. If not set, the default is N.
    Boolean
    disable_normalize_time Enables SAP 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, SAP Mobile Services normalizes the values. For example, if the value of an EDM.Time type attribute is PT01D08M20S, SAP Mobile Services normalizes it to PT1D8M20S and saves it to a varchar type, so it affects the column sort. When set to Y, SAP Mobile Services retains the original values from the back-end server, without normalization. Boolean
    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, SAP Mobile Services adds an 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. Boolean
    early_populate_backend_generated_values Indicates 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. Boolean
    log_request_headers_when_bad_request Indicates whether to log request headers. The default is N. When set to Y, SAP Mobile Services logs the request headers when meeting bad requests. If not set the default is N. Boolean
    wait_shared_cache_updated Enter Y to indicate that when a shared defining query is synchronized, and SAP Mobile Services finds that the defining query cache is being updated, the current sync waits until the cache is updated, in order to download the latest data. If not set the default is N. Boolean
    not_populate_refconstraint Disable sending referential constraint data to the client. When set to Y, SAP Mobile Services does not populate the client with referential constraint data during the initial download. The benefits are that the database size is decreased and the initial download performance is improved, but query processing may take a little longer on the client. If not set, the default is N. You can also change the setting from Y to N to pause the behavior temporarily. Boolean
    ignore_stream_request_4xx_error Temporarily ignore some 4xx errors. By design, when the client sets a definingQuery with automaticallyRetrievesStreams=true and the back-end server returns a 4xx code for some streams, the sync between client and back-end server terminates. When set to Y, SAP Mobile Services ignores these 4xx errors and lets the sync continue, loading the other streams instead of breaking the sync. The option is useful when back-end media entities are not stable, and the media content is not immediately required on the device after the initial download. One limitation is that the ignored media content will not be downloaded again until its entity is updated (some properties are changed or its etag is changed). If not set, the default is N. You can also change the setting from Y to N to pause the behavior temporarily. Boolean
    send_original_repeatability When set, the client sends repeatable requests in accordance with the original (2013) specification. Set "Y" (the default) to indicate repeatable requests should be sent using the 2013 specification. Set to "N" to indicate that the 2013 standard is not used. Boolean
    send_standard_repeatability When set, the client sends repeatable requests in accordance with the standard (2020) specification. Set to "Y" to indicate repeatable requests should be sent using the 2020 specification. Set to "N" (the default) to indicate that the 2020 standard is not used. Boolean
  6. In Client Indexes, click add to add client index parameters, and then click Next.

    The index parameters are for the client database that is used for offline storage. This enables you to configure specific actions for a client database entity, such as sort data in ascending or descending order.

    Client Index Properties

    Property Description
    Entity Type Name Enter the client database EntityTypeName, in the format <namespace>.<EntityTypeName1>. For example, Sample.Customer.
    Properties Enter one or more property names, for which to create the EntityTypeName index, in the format Property1A[ASC|DESC][, Property1B[ASC|DESC][, ...]. The default is ascending order if no entry is made. For example, FirstName, Nick.
    Action The action to take for the index paramter row, such as Delete.

    See Application Configuration File for more information about indexed_type.

  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 Whether to use mobile services to send a delta response to the client even if the back end can’t support a delta query. You can specify Auto, Always, or Never as described for Delta Tracking in step 4, the Delta Tracking Property Details table. Note that if you specified a Delta Tracking value for Endpoint Properties in step 4, the same value is automatically used for Delta Tracking in Defining Requests. You can leave this blank to use the same value; or you can specify a different value for Defining Requests.
    Token Lifetime (min) The time, in minutes, until the OData delta token expires. This value controls how long the oldest change log data are retained.

    While valid, only changed data is downloaded to the offline store. When the delta token expires, the entire data set is replaced. The default is 21600 minutes (about 15 days). This value is recommended for optimal database usage and performance of the mobile service.
    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.

Default and custom trust configuration must already be established in SAP Business Technology Platform cockpit.

For information about establishing trust, see Configuring Security Trust and Establish Trust and Federation with UAA Using Any SAML Identity Provider.

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: January 25, 2024