Skip to content

Application Configuration File

Use the application configuration file to configure OData endpoints and defining queries that determine the data that populates the client database (the offline store) when it is created. Use the cockpit to import the application configuration file.

An application configuration file consists of one or more OData endpoints, each of which can be optionally followed by one or more defining queries.

Each application configuration file represents a single application. All settings have default values, so an application configuration file is only required for non-default behaviors.

An endpoint is configured with a set of parameters:

[endpoint]
name=YourConnectionName
prepopulate_offline_db=Y|N|SHARED-ONLY
prepopulate_offline_db_interval=NNN
indexed_type=<namespace>.<entity type name1>: Property1A [ASC|DESC][, Property1B [ASC|DESC], ...]
indexed_type=<namespace>.<entity type name2>: Property2A [ASC|DESC][, Property2B [ASC|DESC], ...]
defining_query_format=application/json;q=1,application/atom+xml;q=0.5
delta_query_format=application/atom+xml
offline_db_collation=UTF8BIN
case_sensitive_offline_db=Y|N
json_datetimeoffset_in_utc=Y|N
local_change_expiry=NNN
allow_omitting_max_length_facet=Y|N
content_id_header_location=mime|operation
max_delta_resends=NNN
allow_defining_query_removal=Y|N

The table below lists parameters that can be used to configure endpoints in an application configuration file.

Parameter Value Notes
name Valid String (Required) The name of the endpoint, which is the same as Connection Name in the cockpit.
prepopulate_offline_db (for NEO) N or SHARED-ONLY Specifies the type of data that is prepopulated when creating a new database.
  • N Creates an empty database with only a schema. The database is refreshed automatically after it is deployed to the client to obtain data.
  • SHARED-ONLY The database includes only shared data and no user-specific data. The database is refreshed automatically after it is deployed to the client to obtain user-specific data.

The default value is N.

prepopulate_offline_db (for Cloud Foundry) Y or N or SHARED-ONLY Specifies the type of data that is prepopulated when creating a new database.
  • Y Both shared and unshared data is included in the database when it is created on the server. The fully populated database, as defined by the defining queries, is deployed to the client.
  • N Creates an empty database with only a schema. The database is refreshed automatically after it is deployed to the client to obtain data.
  • SHARED-ONLY The database includes only shared data and no user-specific data. The database is refreshed automatically after it is deployed to the client to obtain user-specific data.

The default value is Y.

prepopulate_offline_db_interval NNN If a download requires a new database, the shared data is refreshed based on the interval specified, in minutes. This option applies only when prepopulate_offline_db is set to Y or SHARED-ONLY and there is at least one defining query with is_shared_data=Y.

The default is 1440 minutes (one day).

indexed_type &lt;namespace&gt;.&lt;entity type name&gt;: PropertyName [ASC or DESC][, AnotherPropertyName [ASC or DESC], ...] The left-side value is the entity type name and the right-side value is a comma-delimited list of properties, each of which can optionally be suffixed with ASC or DESC. Each indexed_type creates an index on the client database. Defining indexes can improve client query performance. However, defining too many indexes can slow the performance of downloads and updates. Specify multiple indexed_type entries by listing one entry per line.

Specify either the primitive property name, or a complex type path expression that ends with a primitive property.

    For example:
    indexed_type=SAPODataExample.CustomerType:Surname,GivenName
    indexed_type=SAPODataExample.CustomerType:Address/Province,Address/City

Tip:

  • indexed_type entries are for new registrations; changing the setting does not create or re-create indexes. However, deleting the application from the client has the same effect as deleting the registration.
  • in the mobile services debug logs, lines that start with “Ignoring index creation” indicate that something is misconfigured.
defining_query_format atom or json or any valid value The format to use when communicating with the OData service. This property applies only when the offline store is making initial requests or non-delta requests to the OData service.
  • atom application/atom+xml.
  • json application/json.
  • any valid value Any valid value for an Accept Header.

The default is application/json;q=1,application/atom+xml;q=0.5.

delta_query_format atom or json or any valid value The format to use when communicating with the OData service. This property applies only when the offline store is making delta requests to the OData service.
  • atom application/atom+xml.
  • json application/json.
  • any valid value Any valid value for an Accept Header.

The default is application/atom+xml.

offline_db_collation Any collation supported by UltraLite The collation for the database.

The default is UTF8BIN.

case_sensitive_offline_db Y or N Whether the database is case sensitive.

The default value is Y.

json_datetimeoffset_in_utc Y or N Whether the OData service specifies or accepts the ticks portion of a JSON-formatted Edm.DateTimeOffset in UTC or in the timezone specified by the offset portion.
  • Y The OData service accepts the ticks portion of a JSON formatted Edm.DateTimeOffset in UTC.
  • N The OData service accepts the ticks portion of a JSON formatted Edm.DateTimeOffset in the time zone that is specified in the offset portion.

The default value is Y.

local_change_expiry NNN In some cases, local changes may remain in the offline store after it has been uploaded to the back end. To prevent this, specify a life span, in hours, for local data. When this option is omitted from the configuration file, local changes never expire.
  • Negative value Local changes never expire.
  • Zero Local changes expire during the next download.
  • Positive value Local changes expire during the first download after the specified number of hours have passed.
allow_omitting_max_length_facet Y or N When enabled, allows default MaxLength values for Edm.String and Edm.Binary key properties to be assigned by the system when none are provided. Any indexable properties (key or referential constraint) that are missing the MaxLength facet are treated as though they have a MaxLength of 1536 bytes.
  • Y The system assigns default MaxLength values when they are not provided in the OData metadata.
  • N The system does not assign default MaxLength values so they must be provided in the OData metadata.

The default value is N.

Note: This feature is intended only for development purposes as it does not provide fine-tuned control over the values chosen. In a production environment, ensure MaxLength facets for Edm.String and Edm.Binary key properties are included in the OData metadata.

content_id_header_location mime or operation In a batch request, the header section of the OData change set to put the ContentID header.
  • mime The ContentID header is included in the mime header section of the OData change set.
  • operation The ContentID header is included in the operation header section of the OData change set. Use this option when the back end does not allow the ContentID header to be in the mime header section.

The default value is mime.

max_delta_resends NNN When multiple defining queries are delta enabled, the delta requests are automatically sent to the back end repeatedly until all delta responses are empty, to ensure data consistency. Use this option to configure the number of times a delta link is sent during a download.

The default value is 5.

batch_all_defining_queries Y or N If Y, all defining queries under the endpoint are sent in one batch operation.

The default is N.

refresh_in_order Y or N Whether to download data in the order in which the defining queries appear in the configuration file. If Y, the defining queries are executed in the order in which they are defined in the configuration file.

The default value is N.

check_repeatable_requests Y or N To enable repeatable requests, set:

[endpoint]
name=myEndpoint
check_repeatable_requests=Y

If using an OData service that supports repeatable requests (such as Netweaver gateway), you do not need to enable check_repeatable_requests. When implemented in the OData service, protection is provided from all comunication errors. Whereas if you enable check_repeatable_requests, you are only protected against communication errors between the client and the mobile services. Communication errors between the mobile services to the OData service can still lead to issues. However if you are using an OData service without repeatable requests enabled you must enable check_repeatable_requests. See Repeatable Requests for additional details.

The default value is N.

repeatable_requests_lifetime NNN Repeatable requests require space in your database tenant to track which requests have received responses. Set repeatable_requests_lifetime to control how long, in minutes, responses are saved.

The default value is 72000 (50 days). This setting needs to be large enough to handle devices that sit idle for some time.

For example, if a communication error occurs at the end of a Friday, you'd want to keep the saved responses until at least the following Monday (3 days). For example:

[endpoint]
name=myEndpoint
check_repeatable_requests=Y
repeatable_requests_lifetime=4320

allow_defining_query_removal Y or N Whether allow the client to remove defining queries.

The default value is N.

When batch_all_defining_queries=N, multiple defining queries can be grouped into one batch request as specified in a [defining_query_group] section. For example:

[defining_query_group]
defining_queries=req1,req2,req3
[defining_query_group]
defining_queries=req4,req5,req6
Parameter Value Notes
defining_queries Comma separated list of defining query names. Defining queries specified in the same defining_query_group are sent in one batch request.
  • When defining_query_group is defined, you cannot set batch_all_defining_queries to Y.
  • If batch_all_defining_queries is set to Y, all the defining queries are executed in a batch request.
  • Defining queries not belonging to any group are executed individually if batch_all_defining_queries is set to N.

Last update: November 5, 2020