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 optionally be 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 required only for non-default behaviors.

An endpoint is defined as follows:

[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
early_populate_backend_generated_values=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 are 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`	<namespace>.<entity type name>: 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 recreate 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. Indexing on properties of spatial types is not supported.
`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. Please note that an initial download is required for this change to take effect. 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 client to remove defining queries. The default value is `N`.
`early_populate_backend_generated_values`	Y or N	When creating an entity locally, sometimes not all the values are available, such as the primary key. These values will be generated by the back end when called during upload. If this option is set to `Y`, the server will populate 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` (the default), after uploading the new entity, the primary property of the local entity will still be empty and it will have to be populated in the next download. But when this option is `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: Turning this option on might have an effect on upload performance. Currently, this feature only supports entity creation and does not support entity patching or updating.

When batch_all_defining_queries=N, multiple defining queries can be grouped into one batch request as instructed 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 defined queries names	Defining queries that are 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, then all the defining queries are executed in a batch.
Defining queries not belonging to any group are executed individually if batch_all_defining_queries is set to N.

Editing the Application Configuration File¶

Use the Offline editor to make updates to the application configuration file.

On the Offline tab, select the icon.
Specify endpoint properties and click Next.
In the Endpoint Customized Properties section, click to add private parameters and click Next.
Add the client index parameters and click Next.
Add the defining request parameters and click Next.
Add any defining request groups and click Finish.

Last update: June 15, 2023