Administrator

Application Configuration File

Use the application configuration file to configure OData endpoints and defining requests that determine the data that populates the application database 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 requests.

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

Endpoints are 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], …]
request_format=application/json;q=1,application/atom+xml;q=0.5
delta_request_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
Parameter Value Notes
name Name (Required) The name of the endpoint, defined as a Connection Name in the cockpit.
prepopulate_offline_db Y|N|SHARED-ONLY Specifies the type of data that is included in the initial database.
  • Y Shared and unshared data is included in the client database when it is created on the server. The fully populated database, as defined by the defining requests, is deployed to the client. This is the default value.
  • N Creates an empty database with only a schema. To obtain data, the database is refreshed automatically after it is deployed to the client.
  • Shared-only The database includes only shared data and no user-specific data. To obtain client-specific data, the database is refreshed automatically after it is deployed to the client.
prepopulate_offline_db_interval NNN If a refresh requires a new database, the shared data is refreshed based on the interval specified, in minutes. The default is 1440 minutes (one day).

This option applies only when prepopulate_offline_db is set to Y or SHARED-ONLY and there is at least one defining request with is_shared_data=Y.

indexed_type <namespace>.<entity type name>: PropertyName [ASC|DESC][, AnotherPropertyName [ASC|DESC], …] Each indexed_type defined causes the client database to have an index for that type. Defining indexes can improve client query performance. However, defining too many indexes can slow the performance of refreshes 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.

request_format atom|json|any valid value Specifies the format to use when communicating with the OData producer. This property applies only when the offline OData service is making initial requests or non-delta request to the OData producer.
  • atom Short for application/atom+xml.
  • json Short for application/json.
  • Any valid value Specify any valid value for an Accept header.
The default is:
application/json;q=1,application/atom+xml;q=0.5
delta_request_format atom|json|any valid value Specifies the format to use when communicating with the OData producer. This property applies only when the offline OData service is making delta requests to the OData producer.
  • atom Short for application/atom+xml.
  • json Short for application/json.
  • Any valid value Specify any valid value for an Accept header.
The default is:
application/atom+xml
offline_db_collation

Any collation supported by UltraLite.

Specifies the collation for the database.

The default is:
UTF8BIN
case_sensitive_offline_db Y|N

Specifies whether the database is case sensitive.

The default is:
case_sensitive_offline_db=Y
json_datetimeoffset_in_utc Y|N

Specifies whether the OData backend 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 backend accepts the ticks portion of a JSON formatted Edm.datetimeoffset in UTC.
  • N The OData backend accepts the ticks portion of a JSON formatted Edm.datetimeoffset in the timezone that is specified in the offset portion.
The default is:
json_datetimeoffset_in_utc=Y
local_change_expiry NNN

In some cases, local data could persist in the local store after it has been flushed to the back end. To prevent this, specify an expiry, 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 Causes local changes to expire during the next refresh.
  • Positive value Causes local changes to expire during the first refresh after the specified number of hours have passed.
allow_omitting_max_length_facet Y|N

When enabled, this option 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 is:
allow_omitting_max_length_facet=N
content_id_header_location

mime|operation

For a batch request, specifies which header section of the OData changeset to put the ContentID header in.

  • mime The ContentID header is included in the mime header section of the OData changeset.
  • operation The ContentID header is included in the operation header section of the OData changeset. Use this option when the back end does not allow the ContentID header to be in the mime header section.
The default is:
content_id_header_location=mime
max_delta_resends

NNN

When multiple defining requests are delta-enabled, the delta requests are automatically sent to the backend repeatedly until all delta responses are empty in order to ensure data consistency. Use this option to configure the number of times a delta link is resent during a refresh.

The default is 5.

Create defining requests as follows:

[defining_request]
name=DefiningRequestName
is_shared_data=N|Y
refresh_interval=NNN
track_deltas=AUTO|ALWAYS|NEVER
delta_token_lifetime=NNN

Currently, only defining requests where the resource path identifies an entity set or entity type instance are supported.

Parameter Value Notes
name DefiningRequestName (Required) The name of the defining request. A defining request is an OData read request that targets the OData endpoint associated with the offline store, and retrieves a subset of the OData endpoint data.

Defining requests are defined in the ODataOfflineStoreOptions object of the OData Offline API. The application populates the “definingRequests” parameter.

is_shared_data N|Y Specifies whether the data is shared among different clients or users.
  • N At least some data is not shared amongst multiple client databases. This is the default value.
  • Y All data in the request is shared among multiple client databases.
refresh_interval NNN The interval time, in minutes, between refreshes of the shared data. The default is 15 minutes.
track_deltas AUTO|ALWAYS|NEVER Specifies how to track OData deltas.
  • Auto If the OData producer supports delta change tracking on the defining request, the delta links returned are used when refreshing the data. If the OData producer does not support delta change tracking on the defining request, the server tracks the changes so that only changed data is exchanged between the client and the server. This is the default value.
  • Never Sets the server to never track delta changes. If the OData producer supports delta change tracking, the delta links returned by the OData producer are used when refreshing data, even if this option is specified.
  • Always Sets the server to always track delta changes. This option is equivalent to Auto if the OData producer does not support delta change tracking on the defining request.
delta_token_lifetime NNN

The time, in minutes, until the OData delta token expires. The default is 72000 minutes (50 days).

While a token is valid, only changed data is refreshed on the client database. When the delta token expires, the entire client database is replaced.