Create a connection to OData by navigating to the Connections page in the Sync App application and selecting the corresponding icon in the Add Connections panel. If the OData icon is not available, click the Add More icon to download and install the OData connector from the CData site.

Required properties are listed under the Settings tab. The Advanced tab lists connection properties that are not typically required.

Connecting to OData

To connect, you need to set the Url to a valid OData service root URI in addition to the authentication values.

Authenticating to OData

The Sync App supports following authentication schemes.

HTTP Auth Schemes

The following general HTTP Auth schemes are supported:

• None: If no authentication is required, set the AuthScheme to None.
• Basic: If Basic Auth is supported, set the AuthScheme to Basic. In addition, set the User and Password.
• NTLM: A type of Windows authentication often used across a LAN using your Windows user credentials. Set the AuthScheme to NTLM to support this method of authentication. In addition, set the User and Password if you are not connecting from a Windows machine, or your currently logged in user account should not be used for the connection.
• Digest: If Digest Auth is supported, set the AuthScheme to Digest. In addition, set the User and Password.

Kerberos

OAuth

Set the AuthScheme to OAuth. See Using OAuth Authentication for an authentication guide.

Authenticating with AzureAD

AzureAD is a form of OAuth that goes through Azure. Set the AuthScheme to AzureAD. The CData Sync App will internally automatically take care of known Azure URLs. Specifically, the following are unnecessary to specify with the AzureAD AuthScheme:

• OAuthAccessTokenURL
• OAuthAuthorizationURL
• OAuthRefreshTokenURL
• OAuthRequestTokenURL

Other connection properties may be required for this connection method including:

• Scope: Must be specified if InitiateOAuth is set to GETANDREFRESH as the Scope is submitted to Microsoft during retrieval of credentails. This will vary depending on the service, but is generally a combination of the resource (hostname in the URL) and permission name. For example: https://host/user_impersonation.
• AzureADTenant: The specific Azure Tenant to authenticate against during Microsoft login. If none is specified, your user account's default tenant via the common login endpoint will be used. This may not be correct depending on the specific resource you are connecting to. For example, if the resource is stored on a seperate tenant for cases where you have access to multiple tenants.

Otherwise, the steps are identical to the Using OAuth Authentication guide.

SharePoint Online

SharePoint Online connections may be established by retrieving a SharePoint Online cookie. Specify the following connection properties to authenticate:

• AuthScheme: Set this to SharePointOnline.
• User: Set this to your SharePoint Online user account.
• Password: Set this to your SharePoint Online password.

Kerberos

Please see Using Kerberos for details on how to authenticate with Kerberos.

Securing OData Connections

By default, the Sync App attempts to negotiate SSL/TLS by checking the server's certificate against the system's trusted certificate store. To specify another certificate, see the SSLServerCert property for the available formats to do so.

This section shows how to use the Sync App to authenticate using Kerberos.

Kerberos

To authenticate to OData using Kerberos, set the following properties:

• AuthScheme: Set this to NEGOTIATE.
• KerberosKDC: Set this to the host name or IP Address of your Kerberos KDC machine.
• KerberosSPN: Set this to the service and host of the OData Kerberos Principal. This is the value prior to the '@' symbol (for instance, ServiceName/MyHost) of the principal value (for instance, ServiceName/[email protected]).

Retrieve the Kerberos Ticket

You can use one of the following options to retrieve the required Kerberos ticket.

MIT Kerberos Credential Cache File

This option enables you to use the MIT Kerberos Ticket Manager or kinit command to get tickets. Note that you do not need to set the User or Password connection properties with this option.

1. Ensure that you have an environment variable created called KRB5CCNAME.
2. Set the KRB5CCNAME environment variable to a path pointing to your credential cache file (for instance, C:\krb_cache\krb5cc_0 or /tmp/krb5cc_0). This file is created when generating your ticket with MIT Kerberos Ticket Manager.
3. To obtain a ticket, open the MIT Kerberos Ticket Manager application, click Get Ticket, enter your principal name and password, then click OK. If successful, ticket information appears in Kerberos Ticket Manager and is stored in the credential cache file.
4. Now that you have created the credential cache file, the Sync App uses the cache file to obtain the Kerberos ticket to connect to OData.

As an alternative to setting the KRB5CCNAME environment variable, you can directly set the file path using the KerberosTicketCache property. When set, the Sync App uses the specified cache file to obtain the Kerberos ticket to connect to OData.

Keytab File

If the KRB5CCNAME environment variable has not been set, you can retrieve a Kerberos ticket using a Keytab File. To do so, set the User property to the desired username and set the KerberosKeytabFile property to a file path pointing to the keytab file associated with the user.

User and Password

If both the KRB5CCNAME environment variable and the KerberosKeytabFile property have not been set, you can retrieve a ticket using a user and password combination. To do this, set the User and Password properties to the user/password combination that you use to authenticate with OData.

Cross-Realm

More complex Kerberos environments may require cross-realm authentication where multiple realms and KDC servers are used (e.g., where one realm/KDC is used for user authentication and another realm/KDC is used for obtaining the service ticket).

In such an environment, set the KerberosRealm and KerberosKDC properties to the values required for user authentication. Also set the KerberosServiceRealm and KerberosServiceKDC properties to the values required to obtain the service ticket.

Customizing API Requests

The following properties provide the granular control useful for integrating with nonstandard APIs or to access more advanced OData functionality.

• CustomUrlParams: Set this to append query string parameters onto the request that the Sync App builds.

  Note that if this property is not set you must set Url to the service document to avoid an error.

• ContinueOnError: The Sync App builds batch requests to OData 4.0 services when batch APIs in the underlying driver interface are invoked; for example, when your application makes a batch request.

  When this property is set, errors are returned in a temporary table to avoid breaking execution.

• UseEtags: Etags can be used by OData clients to check if a resource has changed on the server and avoid concurrency problems.
  If you do not need to surface this functionality or if your OData service does not return Etags, set this property to false.
• Cookies: If you need to provide cookies obtained outside the Sync App, you can set them in this value.
• CustomHeaders: You can use this property to add any value to any HTTP request header.

Fine Tuning Data Access

Set the following properties to control how the Sync App models OData APIs as a database:

• NavigationPropertiesAsViews: By default, the Sync App models navigation properties as views.
  This enables access to related entities, even though these entities may not be linked by a foreign key in your OData service.
• SupportsExpand: If your API does not support the $expand parameter, set this property to avoid an error when NavigationPropertiesAsViews is set.
  If this is the case for your API, specify the base entity's primary key in the WHERE clause to access navigation properties.
• DataFormat: Set this property to JSON or XML. Otherwise, the Sync App uses the default format defined by the service.
• ODataVersion: Use this to override the version detected by the Sync App. This is useful if your application supports an older OData version.
• UseIdUrl: By default the Sync App returns the direct URL to an entity as the primary key. By setting this to false, the entity key is returned.
• UseSimpleNames: Set this to true to return only alphanumeric characters in column names. This can help you to avoid SQL escapes and errors in SQL-based tools.
• ServerTimeZone: By default, the Sync App assumes the server's Edm.DateTime values are GMT and converts them to and from the installed machine's local timezone accordingly.
  If the server's Edm.DateTime values are known to apply to a different timezone, then set this property to that timezone (i.e. EST).

This section details a selection of advanced features of the OData Sync App.

User Defined Views

The Sync App allows you to define virtual tables, called user defined views, whose contents are decided by a pre-configured query. These views are useful when you cannot directly control queries being issued to the drivers. See User Defined Views for an overview of creating and configuring custom views.

SSL Configuration

Use SSL Configuration to adjust how Sync App handles TLS/SSL certificate negotiations. You can choose from various certificate formats; see the SSLServerCert property under "Connection String Options" for more information.

Firewall and Proxy

Configure the Sync App for compliance with Firewall and Proxy, including Windows proxies and HTTP proxies. You can also set up tunnel connections.

Query Processing

The Sync App offloads as much of the SELECT statement processing as possible to OData and then processes the rest of the query in memory (client-side).

See Query Processing for more information.

Logging

See Logging for an overview of configuration settings that can be used to refine CData logging. For basic logging, you only need to set two connection properties, but there are numerous features that support more refined logging, where you can select subsets of information to be logged using the LogModules connection property.

Customizing the SSL Configuration

By default, the Sync App attempts to negotiate SSL/TLS by checking the server's certificate against the system's trusted certificate store.

To specify another certificate, see the SSLServerCert property for the available formats to do so.

Client SSL Certificates

The OData Sync App also supports setting client certificates. Set the following to connect using a client certificate.

• SSLClientCert: The name of the certificate store for the client certificate.
• SSLClientCertType: The type of key store containing the TLS/SSL client certificate.
• SSLClientCertPassword: The password for the TLS/SSL client certificate.
• SSLClientCertSubject: The subject of the TLS/SSL client certificate.

Connecting Through a Firewall or Proxy

HTTP Proxies

To connect through the Windows system proxy, you do not need to set any additional connection properties. To connect to other proxies, set ProxyAutoDetect to false.

In addition, to authenticate to an HTTP proxy, set ProxyAuthScheme, ProxyUser, and ProxyPassword, in addition to ProxyServer and ProxyPort.

Other Proxies

Set the following properties:

• To use a proxy-based firewall, set FirewallType, FirewallServer, and FirewallPort.
• To tunnel the connection, set FirewallType to TUNNEL.
• To authenticate, specify FirewallUser and FirewallPassword.
• To authenticate to a SOCKS proxy, additionally set FirewallType to SOCKS5.

The CData Sync App models OData entities in relational Tables, Views, and Stored Procedures. The table definitions are dynamically obtained from the OData service you connect to. Any changes in the metadata, such as added or removed columns or changes in data type, can be loaded by reconnecting.

Tables

The Sync App models the writable entity sets and singletons described in the service metadata document as bidirectional Tables.

Views

Some OData entities can only be accessed through Navigation Properties. By default, the Sync App models navigation properties as separate views. You can disable this behavior with NavigationPropertiesAsViews. See Views for more information on querying navigation properties.

Stored Procedures

Stored Procedures are function-like interfaces to the data source. They can be used to search, update, and modify information in the data source.

The Sync App exposes tables for every entity set and singleton defined on the OData service document. Entities on these tables may be inserted, updated, or deleted using standard SQL insert, update, or delete statements.

Executing Deep Inserts with SQL

The Sync App supports OData deep inserts, in which you simultaneously create a base entity and link it to related entities, by specifying navigation properties. To specify Navigation Properties for an entity, you may either submit JSON / XML data, or you may create a temporary table for the navigation property and then reference the temporary table in the insert to the base table. Sumit the XML / JSON or reference the temporary table in the appropriate navigation property column on the base table. Each navigation property column is prefixed with the word "Linked".

Example: Deep Inserts using XML / JSON

To submit XML or JSON data, simply supply the values for the table the navigation property is referencing in XML or JSON format. If you are familiar with the OData standard, you should not be submitting values in the standard. The XML / JSON used here is simply a means of supplying multiple values ot the CData Sync App.

For example, consider the Orders table in Northwind odata.org test service. To create a new Order, you specify the Products ordered, Customer, Employee, and Shipper. To do so, you need to specify the Customer, Order_Details, Shipper, and Employee navigation properties.

• Customer: The following XML represents a new Customer:
  

    <Row>
      <CustomerID>VINET</CustomerID>
  	<CompanyName>Vins et alcools Chevalier</CompanyName>
  	<ContactName>Paul Henriot</ContactName>
  	<ContactTitle>Accounting Manager</ContactTitle>
  	<Address>59 rue de l'Abbaye</Address>
  	<City>Reims</City>
  	<PostalCode>51100</PostalCode>
  	<Country>France</Country>
  	<Phone>26.47.15.10</Phone>
  	<Fax>26.47.15.11</Fax>
    </Row>

• Order_Details: The following JSON add two Products to the Order:
  

    [
      {
  	  "ProductID": 72,
  	  "UnitPrice": 34.80,
  	  "Quantity": 5,
  	  "Discount": 0
  	},
  	{
  	  "ProductID": 42,
  	  "ProductID": 9.80,
  	  "ProductID": 10,
  	  "ProductID": 0
  	}
    ]

• Employee: The following XML specifies the existing Employee:
  

    <Row>
      <EmployeeID>5</EmployeeID>
    </Row>

• Shipper: The following JSON specifies the existing Shipper:
  

    [
      {
        "ShipperID": 3
      }
    ]

In order to execute the insert, simply reference or include as string literals the complete XML / JSON. For example:

INSERT INTO Orders (CustomerID, EmployeeID, ShipVia, ShipName, ShipAddress, ShipCity, ShipPostalCode, ShipCountry, OrderDate, LinkedOrder_Details, LinkedCustomer, LinkedEmployee, LinkedShipper) VALUES ('VINET', 5, 3, 'Paul Henriot', '59 rue de l''Abbaye', 'Reims', '51100', 'France', '07/04/1996', '{ ... }', '<Row>...</Row>', ?, ?)

Example: Deep Inserts using Temporary Tables

If using temporary tables, they must be defined and inserted within the same connection. Closing the connection will clear out any temporary tables in memory. Keeping with the Northwind example, you need to specify the following navigation properties.

Creating Temporary Tables

Insert the related entities into temporary tables that correspond to each navigation property. You can specify an existing entity's primary key or you can insert a new entity.

• Customer: The following statement creates a new Customer:
  

  INSERT INTO Customers#TEMP (CustomerID, CompanyName, ContactName, ContactTitle, Address, City, PostalCode, Country, Phone, Fax) 
  VALUES ('VINET', 'Vins et alcools Chevalier', 'Paul Henriot', 'Accounting Manager', '59 rue de l''Abbaye', 'Reims', '51100', 'France', '26.47.15.10', '26.47.15.11')

• Order Details: The following statements add two Products to the Order:
  

  INSERT INTO Order_Details#TEMP (ProductID, UnitPrice, Quantity, Discount) VALUES (72, 34.80, 5, 0)
  
  INSERT INTO Order_Details#TEMP (ProductID, UnitPrice, Quantity, Discount) VALUES (42, 9.80, 10, 0)

• Employee: The following statement specifies the existing Employee:
  

  INSERT INTO Employees#TEMP (EmployeeID) 
  VALUES (5)

• Shipper: The following statement specifies the existing Shipper:
  

  INSERT INTO Shippers#TEMP (ShipperID) VALUES (3) 

The CData Sync App will assume that the Shipper and Employee already exist and will only link to the existing references since only the primary keys were specified for either. When more than just the primary key is defined, such as the examples for Customer and Order_Details, the CData Sync App will attempt to create new entries - triggering the deep insert.

Inserting the Entity

In the INSERT statement for the base entity, reference the temporary tables in the LinkedOrder_Details, LinkedCustomer, LinkedEmployee, and LinkedShipper columns:

INSERT INTO Orders (CustomerID, EmployeeID, ShipVia, ShipName, ShipAddress, ShipCity, ShipPostalCode, ShipCountry, OrderDate, LinkedOrder_Details, LinkedCustomer, LinkedEmployee, LinkedShipper) VALUES ('VINET', 5, 3, 'Paul Henriot', '59 rue de l''Abbaye', 'Reims', '51100', 'France', '07/04/1996', 'Order_Details#TEMP', 'Customers#TEMP', 'Employees#TEMP', 'Shippers#TEMP')

Modeling Navigation Properties

By default, the Sync App models Navigation Properties as separate views. The views are named in the format ParentTable_NavigationProperty. You can disable this behavior with NavigationPropertiesAsViews.

Querying Navigation Properties

For an example of working with a navigation property as a view, consider the Northwind sample service from odata.org. In this service, the Categories entity set has a Products navigation property. The CData Sync App will display a view called Categories_Products for this service. Retrieving data from Categories_Products will display all of the Products associated with a given Category. The Categories_Products view has a primary key made up of the Id of the parent entity and the Id of the related entity.

Support for navigation properties is limited in some OData services. See NavigationPropertiesAsViews and SupportsExpand for more information on API restrictions when querying navigation properties.

In OData, a navigation property is a property on an entity that is itself either a single entity or list of entities.

A single-entity navigation property signifies a one-to-one relationship; for example, an OData service might allow a Product to have only one Category. In this service, Category might be a navigation property on Products.

An entity set navigation property signifies a one-to-many relationship; for example, many Products can belong in the same Category. In this service, Products might be a navigation property on Categories.

Working with Navigation Properties Relationally

Navigation properties in OData link related entities. Similarly, in a relational database, a foreign key serves to link tables. For example, a Product record might have a CategoryId column, which uniquely identifies what Category the Product belongs to. However, there is no requirement in OData that an entity must contain a foreign key reference to a related entity. This means sometimes you will get navigation properties without having a foreign key reference to that entity on the parent or back to the parent from the related entity. In cases without a foreign key reference, the navigation property's existence is the only thing that can be used to identify a relationship between the two entities.

Select

NavigationPropertiesAsViews is useful for accessing data in OData services that lack foreign key references. Likewise, it can be used to retrieve related entites that do not exist by themselves such as LineItems on an Invoice. See Views for more information on querying navigation properties.

Insert

The Sync App supports OData deep inserts. See Tables for more information on specifying navigation properties when you create an entity.

Data Type Mappings

The Sync App maps types from the data source to the corresponding data type available in the schema. The table below documents these mappings.

The connection string properties are the various options that can be used to establish a connection. This section provides a complete list of the options you can configure in the connection string for this provider. Click the links for further details.

Authentication

Azure Authentication

SSO

OAuth

Kerberos

SSL

Firewall

Proxy

Logging

Schema

Miscellaneous

This section provides a complete list of the Authentication properties you can configure in the connection string for this provider.

URL to the Organization root or the OData services file. For example, http://MySite/MyOrganization.

Remarks

URL to the Organization root or the OData services file. For example, http://MySite/MyOrganization.

The scheme used for authentication. Accepted entries are NTLM, BASIC, DIGEST, NONE, NEGOTIATE, or SHAREPOINTONLINE.

Remarks

Together with Password and User, this field is used to authenticate against the OData server. NONE is the default option.

• None: No authentication for this service.
• AzureAD: Set this to perform Azure Active Directory OAuth authentication.
• Basic: Set this to use HTTP Basic authentication.
• Digest: Set this to use HTTP Digest authentication.
• Negotiate: If AuthScheme is set to NEGOTIATE, the Sync App will negotiate an authentication mechanism with the server. Set AuthScheme to NEGOTIATE if you want to use Kerberos authentication.
• NTLM: Set this to use your Windows credentials for authentication.
• OAuth: Set this to establish an OAuth connection.
• SharePointOnline: Set this to use SharePoint Online authentication.

The OData user account used to authenticate.

Remarks

Together with Password, this field is used to authenticate against the OData server.

The password used to authenticate the user.

Remarks

The User and Password are together used to authenticate with the server.

URL to the OData entity set. For example, http://MySite/MyOrganization/EntitySet.

Remarks

URL to the OData entity set. For example, http://MySite/MyOrganization/EntitySet. You can use this property when the OData service does not have a root document.

Whether or not to use single sign-on (SSO) to authenticate to SharePoint Online.

Remarks

When set to true, single sign-on (SSO) will be used to authenticate to SharePoint Online using the account specified via User and Password. The Active Directory Federation Services (AD FS), OneLogin, and OKTA SSO identity providers are supported.

SharePointSSODomain may be required to be set if the domain configured on the SSO domain is different than the domain of the User.

SSO is only applicable when using SharePoint Online and AuthScheme is set to SHAREPOINTONLINE. It is not available for OAuth connections to SharePoint.

This section provides a complete list of the Azure Authentication properties you can configure in the connection string for this provider.

The Azure Active Directory tenant to authenticate against (only used with Azure AD OAuth).

Remarks

The tenant must be specified if using Azure Active Directory OAuth. The tenant is used to control who can sign into the application. This should be the name of the tenant such as xxx.onmicrosoft.com, the id such as 8eaef023-2b34-4da1-9baa-8bc8c9d6a490, contoso.onmicrosoft.com, or the word common.

The Microsoft Online tenant being used to access data. If not specified, your default tentant will be used.

Remarks

The Microsoft Online tenant being used to access data. For instance, contoso.onmicrosoft.com. Alternatively, specify the tenant Id. This value is the directory Id in the Azure Portal > Azure Active Directory > Properties.

Typically it is not necessary to specify the Tenant. This can be automatically determined by Microsoft when using the OAuthGrantType set to CODE (default). However, it may fail in the case that the user belongs to multiple tenants. For instance, if an Admin of domain A invites a user of domain B to be a guest user. The user will now belong to both tenants. It is a good practice to specify the Tenant, although in general things should normally work without having to specify it.

The AzureTenant is required when setting OAuthGrantType to CLIENT. When using client credentials, there is no user context. The credentials are taken from the context of the app itself. While Microsoft still allows client credentials to be obtained without specifying which Tenant, it has a much lower probability of picking the specific tenant you want to work with. For this reason, we require AzureTenant to be explicitly stated for all client credentials connections to ensure you get credentials that are applicable for the domain you intend to connect to.

The Azure Active resource to authenticate to (used during Azure OAuth exchange).

Remarks

The resource must be specified if using Azure OAuth. It should be set to the App Id URI of the web API (secured resource).

This section provides a complete list of the SSO properties you can configure in the connection string for this provider.

The domain of the user when using single sign-on (SSO).

Remarks

This property is only applicable when using single sign-on (SharePointUseSSO is set to true) and if the domain of the User (e.g. [email protected]) is different than the domain configured within the SSO service (e.g. [email protected]).

This property may be required when using the AD FS, OneLogin, or OKTA SSO services.

This section provides a complete list of the OAuth properties you can configure in the connection string for this provider.

Set this property to initiate the process to obtain or refresh the OAuth access token when you connect.

Remarks

The following options are available:

1. OFF: Indicates that the OAuth flow will be handled entirely by the user. An OAuthAccessToken will be required to authenticate.
2. GETANDREFRESH: Indicates that the entire OAuth Flow will be handled by the Sync App. If no token currently exists, it will be obtained by prompting the user via the browser. If a token exists, it will be refreshed when applicable.
3. REFRESH: Indicates that the Sync App will only handle refreshing the OAuthAccessToken. The user will never be prompted by the Sync App to authenticate via the browser. The user must handle obtaining the OAuthAccessToken and OAuthRefreshToken initially.

The version of OAuth being used.

Remarks

The version of OAuth being used. The following options are available: 1.0,2.0

The client Id assigned when you register your application with an OAuth authorization server.

Remarks

As part of registering an OAuth application, you will receive the OAuthClientId value, sometimes also called a consumer key, and a client secret, the OAuthClientSecret.

The client secret assigned when you register your application with an OAuth authorization server.

Remarks

As part of registering an OAuth application, you will receive the OAuthClientId, also called a consumer key. You will also receive a client secret, also called a consumer secret. Set the client secret in the OAuthClientSecret property.

The access token for connecting using OAuth.

Remarks

The OAuthAccessToken property is used to connect using OAuth. The OAuthAccessToken is retrieved from the OAuth server as part of the authentication process. It has a server-dependent timeout and can be reused between requests.

The access token is used in place of your user name and password. The access token protects your credentials by keeping them on the server.

The OAuth access token secret for connecting using OAuth.

Remarks

The OAuthAccessTokenSecret property is used to connect and authenticate using OAuth. The OAuthAccessTokenSecret is retrieved from the OAuth server as part of the authentication process. It is used with the OAuthAccessToken and can be used for multiple requests until it times out.

The grant type for the OAuth flow.

Remarks

The following options are available: CODE,CLIENT,PASSWORD

How to pass Client Id and Secret with OAuthGrantType is set to Password.

Remarks

The OAuth RFC specifies two methods of passing the OAuthClientId and OAuthClientSecret when using the Password OAuthGrantType. The most commonly used is to pass them via post data to the service. However, some services may require that you pass them via the Authorize header as to be used in BASIC authorization. Change this property to Basic to submit the parameters as part of the Authorize header instead of the post data.

Whether to include the callback URL in an access token request.

Remarks

This defaults to true since standards-compliant OAuth services will ignore the redirect_uri parameter for grant types like CLIENT or PASSWORD that do not require it.

This option should only be enabled for OAuth services that report errors when redirect_uri is included.

The authorization URL for the OAuth service.

Remarks

The authorization URL for the OAuth service. At this URL, the user logs into the server and grants permissions to the application. In OAuth 1.0, if permissions are granted, the request token is authorized.

The URL to retrieve the OAuth access token from.

Remarks

The URL to retrieve the OAuth access token from. In OAuth 1.0, the authorized request token is exchanged for the access token at this URL.

The URL to refresh the OAuth token from.

Remarks

The URL to refresh the OAuth token from. In OAuth 2.0, this URL is where the refresh token is exchanged for a new access token when the old access token expires.

The URL the service provides to retrieve request tokens from. This is required in OAuth 1.0.

Remarks

The URL the service provides to retrieve request tokens from. This is required in OAuth 1.0. In OAuth 1.0, this is the URL where the app makes a request for the request token.

The authentication token used to request and obtain the OAuth Access Token.

Remarks

This property is required only when performing headless authentication in OAuth 1.0. It can be obtained from the GetOAuthAuthorizationUrl stored procedure.

It can be supplied alongside the AuthKey in the GetOAuthAccessToken stored procedure to obtain the OAuthAccessToken.

The authentication secret used to request and obtain the OAuth Access Token.

Remarks

This property is required only when performing headless authentication in OAuth 1.0. It can be obtained from the GetOAuthAuthorizationUrl stored procedure.

It can be supplied alongside the AuthToken in the GetOAuthAccessToken stored procedure to obtain the OAuthAccessToken.

A comma-separated list of other parameters to submit in the request for the OAuth access token in the format paramname=value.

Remarks

A comma-separated list of other parameters to submit in the request for the OAuth access token in the format paramname=value.

This section provides a complete list of the Kerberos properties you can configure in the connection string for this provider.

The Kerberos Key Distribution Center (KDC) service used to authenticate the user.

Remarks

The Kerberos properties are used when using SPNEGO or Windows Authentication. The Sync App will request session tickets and temporary session keys from the Kerberos KDC service. The Kerberos KDC service is conventionally colocated with the domain controller.

If Kerberos KDC is not specified, the Sync App will attempt to detect these properties automatically from the following locations:

• KRB5 Config File (krb5.ini/krb5.conf): If the KRB5_CONFIG environment variable is set and the file exists, the Sync App will obtain the KDC from the specified file. Otherwise, it will attempt to read from the default MIT location based on the OS: C:\ProgramData\MIT\Kerberos5\krb5.ini (Windows) or /etc/krb5.conf (Linux).
• Domain Name and Host: If the Kerberos Realm and Kerberos KDC could not be inferred from another location, the Sync App will infer them from the configured domain name and host.

The Kerberos Realm used to authenticate the user.

Remarks

The Kerberos properties are used when using SPNEGO or Windows Authentication. The Kerberos Realm is used to authenticate the user with the Kerberos Key Distribution Service (KDC). The Kerberos Realm can be configured by an administrator to be any string, but conventionally it is based on the domain name.

If Kerberos Realm is not specified, the Sync App will attempt to detect these properties automatically from the following locations:

• KRB5 Config File (krb5.ini/krb5.conf): If the KRB5_CONFIG environment variable is set and the file exists, the Sync App will obtain the default realm from the specified file. Otherwise, it will attempt to read from the default MIT location based on the OS: C:\ProgramData\MIT\Kerberos5\krb5.ini (Windows) or /etc/krb5.conf (Linux)
• Domain Name and Host: If the Kerberos Realm and Kerberos KDC could not be inferred from another location, the Sync App will infer them from the user-configured domain name and host. This might work in some Windows environments.

The service principal name (SPN) for the Kerberos Domain Controller.

Remarks

If the SPN on the Kerberos Domain Controller is not the same as the URL that you are authenticating to, use this property to set the SPN.

The Keytab file containing your pairs of Kerberos principals and encrypted keys.

Remarks

The Keytab file containing your pairs of Kerberos principals and encrypted keys.

The Kerberos realm of the service.

Remarks

The KerberosServiceRealm is the specify the service Kerberos realm when using cross-realm Kerberos authentication.

In most cases, a single realm and KDC machine are used to perform the Kerberos authentication and this property is not required.

This property is available for complex setups where a different realm and KDC machine are used to obtain an authentication ticket (AS request) and a service ticket (TGS request).

The Kerberos KDC of the service.

Remarks

The KerberosServiceKDC is used to specify the service Kerberos KDC when using cross-realm Kerberos authentication.

In most cases, a single realm and KDC machine are used to perform the Kerberos authentication and this property is not required.

This property is available for complex setups where a different realm and KDC machine are used to obtain an authentication ticket (AS request) and a service ticket (TGS request).

The full file path to an MIT Kerberos credential cache file.

Remarks

This property can be set if you wish to use a credential cache file that was created using the MIT Kerberos Ticket Manager or kinit command.

This section provides a complete list of the SSL properties you can configure in the connection string for this provider.

The TLS/SSL client certificate store for SSL Client Authentication (2-way SSL).

Remarks

The name of the certificate store for the client certificate.

The SSLClientCertType field specifies the type of the certificate store specified by SSLClientCert. If the store is password protected, specify the password in SSLClientCertPassword.

SSLClientCert is used in conjunction with the SSLClientCertSubject field in order to specify client certificates. If SSLClientCert has a value, and SSLClientCertSubject is set, a search for a certificate is initiated. See SSLClientCertSubject for more information.

Designations of certificate stores are platform-dependent.

The following are designations of the most common User and Machine certificate stores in Windows:

In Java, the certificate store normally is a file containing certificates and optional private keys.

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (for example, PKCS12 certificate store).

The type of key store containing the TLS/SSL client certificate.

Remarks

This property can take one of the following values:

The password for the TLS/SSL client certificate.

Remarks

If the certificate store is of a type that requires a password, this property is used to specify that password to open the certificate store.

The subject of the TLS/SSL client certificate.

Remarks

When loading a certificate the subject is used to locate the certificate in the store.

If an exact match is not found, the store is searched for subjects containing the value of the property. If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks the first certificate in the certificate store.

The certificate subject is a comma separated list of distinguished name fields and values. For example, "CN=www.server.com, OU=test, C=US, [email protected]". The common fields and their meanings are shown below.

If a field value contains a comma, it must be quoted.

The certificate to be accepted from the server when connecting using TLS/SSL.

Remarks

If using a TLS/SSL connection, this property can be used to specify the TLS/SSL certificate to be accepted from the server. Any other certificate that is not trusted by the machine is rejected.

This property can take the following forms:

If not specified, any certificate trusted by the machine is accepted.

Use '*' to signify to accept all certificates. Note that this is not recommended due to security concerns.

This section provides a complete list of the Firewall properties you can configure in the connection string for this provider.

The protocol used by a proxy-based firewall.

Remarks

This property specifies the protocol that the Sync App will use to tunnel traffic through the FirewallServer proxy. Note that by default, the Sync App connects to the system proxy; to disable this behavior and connect to one of the following proxy types, set ProxyAutoDetect to false.

To connect to HTTP proxies, use ProxyServer and ProxyPort. To authenticate to HTTP proxies, use ProxyAuthScheme, ProxyUser, and ProxyPassword.

The name or IP address of a proxy-based firewall.

Remarks

This property specifies the IP address, DNS name, or host name of a proxy allowing traversal of a firewall. The protocol is specified by FirewallType: Use FirewallServer with this property to connect through SOCKS or do tunneling. Use ProxyServer to connect to an HTTP proxy.

Note that the Sync App uses the system proxy by default. To use a different proxy, set ProxyAutoDetect to false.

The TCP port for a proxy-based firewall.

Remarks

This specifies the TCP port for a proxy allowing traversal of a firewall. Use FirewallServer to specify the name or IP address. Specify the protocol with FirewallType.

The user name to use to authenticate with a proxy-based firewall.

Remarks

The FirewallUser and FirewallPassword properties are used to authenticate against the proxy specified in FirewallServer and FirewallPort, following the authentication method specified in FirewallType.

A password used to authenticate to a proxy-based firewall.

Remarks

This property is passed to the proxy specified by FirewallServer and FirewallPort, following the authentication method specified by FirewallType.

This section provides a complete list of the Proxy properties you can configure in the connection string for this provider.

This indicates whether to use the system proxy settings or not. This takes precedence over other proxy settings, so you'll need to set ProxyAutoDetect to FALSE in order use custom proxy settings.

Remarks

This takes precedence over other proxy settings, so you'll need to set ProxyAutoDetect to FALSE in order use custom proxy settings.

To connect to an HTTP proxy, see ProxyServer. For other proxies, such as SOCKS or tunneling, see FirewallType.

The hostname or IP address of a proxy to route HTTP traffic through.

Remarks

The hostname or IP address of a proxy to route HTTP traffic through. The Sync App can use the HTTP, Windows (NTLM), or Kerberos authentication types to authenticate to an HTTP proxy.

If you need to connect through a SOCKS proxy or tunnel the connection, see FirewallType.

By default, the Sync App uses the system proxy. If you need to use another proxy, set ProxyAutoDetect to false.

The TCP port the ProxyServer proxy is running on.

Remarks

The port the HTTP proxy is running on that you want to redirect HTTP traffic through. Specify the HTTP proxy in ProxyServer. For other proxy types, see FirewallType.

The authentication type to use to authenticate to the ProxyServer proxy.

Remarks

This value specifies the authentication type to use to authenticate to the HTTP proxy specified by ProxyServer and ProxyPort.

Note that the Sync App will use the system proxy settings by default, without further configuration needed; if you want to connect to another proxy, you will need to set ProxyAutoDetect to false, in addition to ProxyServer and ProxyPort. To authenticate, set ProxyAuthScheme and set ProxyUser and ProxyPassword, if needed.

The authentication type can be one of the following:

• BASIC: The Sync App performs HTTP BASIC authentication.
• DIGEST: The Sync App performs HTTP DIGEST authentication.
• NEGOTIATE: The Sync App retrieves an NTLM or Kerberos token based on the applicable protocol for authentication.
• PROPRIETARY: The Sync App does not generate an NTLM or Kerberos token. You must supply this token in the Authorization header of the HTTP request.

If you need to use another authentication type, such as SOCKS 5 authentication, see FirewallType.

A user name to be used to authenticate to the ProxyServer proxy.

Remarks

The ProxyUser and ProxyPassword options are used to connect and authenticate against the HTTP proxy specified in ProxyServer.

You can select one of the available authentication types in ProxyAuthScheme. If you are using HTTP authentication, set this to the user name of a user recognized by the HTTP proxy. If you are using Windows or Kerberos authentication, set this property to a user name in one of the following formats:

user@domain
domain\user

A password to be used to authenticate to the ProxyServer proxy.

Remarks

This property is used to authenticate to an HTTP proxy server that supports NTLM (Windows), Kerberos, or HTTP authentication. To specify the HTTP proxy, you can set ProxyServer and ProxyPort. To specify the authentication type, set ProxyAuthScheme.

If you are using HTTP authentication, additionally set ProxyUser and ProxyPassword to HTTP proxy.

If you are using NTLM authentication, set ProxyUser and ProxyPassword to your Windows password. You may also need these to complete Kerberos authentication.

For SOCKS 5 authentication or tunneling, see FirewallType.

By default, the Sync App uses the system proxy. If you want to connect to another proxy, set ProxyAutoDetect to false.

The SSL type to use when connecting to the ProxyServer proxy.

Remarks

This property determines when to use SSL for the connection to an HTTP proxy specified by ProxyServer. This value can be AUTO, ALWAYS, NEVER, or TUNNEL. The applicable values are the following:

A semicolon separated list of destination hostnames or IPs that are exempt from connecting through the ProxyServer .

Remarks

The ProxyServer is used for all addresses, except for addresses defined in this property. Use semicolons to separate entries.

Note that the Sync App uses the system proxy settings by default, without further configuration needed; if you want to explicitly configure proxy exceptions for this connection, you need to set ProxyAutoDetect = false, and configure ProxyServer and ProxyPort. To authenticate, set ProxyAuthScheme and set ProxyUser and ProxyPassword, if needed.

This section provides a complete list of the Logging properties you can configure in the connection string for this provider.

Core modules to be included in the log file.

Remarks

Only the modules specified (separated by ';') will be included in the log file. By default all modules are included.

See the Logging page for an overview.

This section provides a complete list of the Schema properties you can configure in the connection string for this provider.

A path to the directory that contains the schema files defining tables, views, and stored procedures.

Remarks

The path to a directory which contains the schema files for the Sync App (.rsd files for tables and views, .rsb files for stored procedures). The folder location can be a relative path from the location of the executable. The Location property is only needed if you want to customize definitions (for example, change a column name, ignore a column, and so on) or extend the data model with new tables, views, or stored procedures.

If left unspecified, the default location is "%APPDATA%\\CData\\OData Data Provider\\Schema" with %APPDATA% being set to the user's configuration directory:

This property restricts the schemas reported to a subset of the available schemas. For example, BrowsableSchemas=SchemaA,SchemaB,SchemaC.

Remarks

Listing the schemas from databases can be expensive. Providing a list of schemas in the connection string improves the performance.

This property restricts the tables reported to a subset of the available tables. For example, Tables=TableA,TableB,TableC.

Remarks

Listing the tables from some databases can be expensive. Providing a list of tables in the connection string improves the performance of the Sync App.

This property can also be used as an alternative to automatically listing views if you already know which ones you want to work with and there would otherwise be too many to work with.

Specify the tables you want in a comma-separated list. Each table should be a valid SQL identifier with any special characters escaped using square brackets, double-quotes or backticks. For example, Tables=TableA,[TableB/WithSlash],WithCatalog.WithSchema.`TableC With Space`.

Note that when connecting to a data source with multiple schemas or catalogs, you will need to provide the fully qualified name of the table in this property, as in the last example here, to avoid ambiguity between tables that exist in multiple catalogs or schemas.

Restricts the views reported to a subset of the available tables. For example, Views=ViewA,ViewB,ViewC.

Remarks

Listing the views from some databases can be expensive. Providing a list of views in the connection string improves the performance of the Sync App.

This property can also be used as an alternative to automatically listing views if you already know which ones you want to work with and there would otherwise be too many to work with.

Specify the views you want in a comma-separated list. Each view should be a valid SQL identifier with any special characters escaped using square brackets, double-quotes or backticks. For example, Views=ViewA,[ViewB/WithSlash],WithCatalog.WithSchema.`ViewC With Space`.

Note that when connecting to a data source with multiple schemas or catalogs, you will need to provide the fully qualified name of the table in this property, as in the last example here, to avoid ambiguity between tables that exist in multiple catalogs or schemas.

This section provides a complete list of the Miscellaneous properties you can configure in the connection string for this provider.

Whether or not to continue after encountering an error on a batch request.

Remarks

This connection property is only supported on servers with OData version 4.0 and higher. However, individual servers may choose to ignore this setting. Setting ContinueOnError to true will cause exceptions to be returned in the temporary table instead of being thrown when a batch request is attempted.

Allows cookies to be manually specified in name=value pairs separated by a semicolon.

Remarks

In general it should not be required to set this property. However, there are many different flavors of OData services. If your solution requires cookies that are obtained outside of the CData Sync App, they can be manually specified here. Specify cookies in name=value pairs separated by a semicolon. For instance: Cookie1=value;Cookie2=value2.

Other headers as determined by the user (optional).

Remarks

This property can be set to a string of headers to be appended to the HTTP request headers created from other properties, like ContentType, From, and so on.

The headers must be of the format "header: value" as described in the HTTP specifications. Header lines should be separated by the carriage return and line feed (CRLF) characters.

Use this property with caution. If this property contains invalid headers, HTTP requests may fail.

This property is useful for fine-tuning the functionality of the Sync App to integrate with specialized or nonstandard APIs.

The custom query string to be included in the request.

Remarks

The CustomUrlParams allow you to specify custom query string parameters that are included with the HTTP request. The parameters must be encoded as a query string in the form field1=value1&field2=value2&field3=value3. The values in the query string must be URL encoded.

The data format to retrieve data in. Select either ATOM or JSON.

Remarks

Note that not all data sources support JSON. Other IANA content types are not supported at this time. Leave blank to use the system service default. If blank, ATOM will be used when submitting data in an insert or update.

Whether or not the CData ADO.NET Provider for OData should use atomic batch operations.

Remarks

Whether or not the CData Sync App should use atomic batch operations.

Indicates if navigation parent columns should be included on navigation views.

Remarks

When NavigationPropertiesAsViews is set to true, this property controls if parent columns from the navigation property will be displayed or not on the view. It may be worth displaying them in order to take advantage of being able to filter based on information about the parent.

When set to false, the primary keys of the parent will still be displayed to allow for joining back to the parent, but other other columns will not be.

Adds a input only ParentReference column for bulk inserts to properly associate children during a deep insert with the same parent.

Remarks

Adds a input only ParentReference column for bulk inserts to properly associate children during a deep insert with the same parent.

Limits the number of rows returned rows when no aggregation or group by is used in the query. This helps avoid performance issues at design time.

Remarks

Limits the number of rows returned rows when no aggregation or group by is used in the query. This helps avoid performance issues at design time.

A boolean indicating navigation properties should be promoted to full views.

Remarks

This property can be useful for OData services that can return related collections of entities, or navigation properties. Some OData entities can only be accessed through navigation properties. NavigationPropertiesAsViews will cause all of the discovered navigation properties to be added as views in the format ParentTable_NavigationProperty.

Retrieving Data from Limited OData APIs

In most cases, NavigationPropertiesAsViews can be left on and the resulting views can be accessed with any SELECT query. However, some OData APIs have limitations that require you to specify the primary key of the parent record when querying a navigation property.

For example:

SELECT * FROM Categories_Products WHERE Categories_CategoryId='1'

You will also need to set SupportsExpand to false. You can find more information on this API limitation in the documentation for the property.

The version of OData to use. By default the provider will attempt to autodetect the version.

Remarks

The version of OData to use. By default the Sync App will automatically attempt to determine the version the service is using. If a version cannot be resolved, 3.0 will be used. This can optionally be manually set.

These hidden properties are used only in specific use cases.

Remarks

The properties listed below are available for specific use cases. Normal driver use cases and functionality should not require these properties.

Specify multiple properties in a semicolon-separated list.

Integration and Formatting

The maximum number of results to return per page from OData.

Remarks

The Pagesize property affects the maximum number of results to return per page from OData. Setting a higher value may result in better performance at the cost of additional memory allocated per page consumed.

This property indicates whether or not to include pseudo columns as columns to the table.

Remarks

This setting is particularly helpful in Entity Framework, which does not allow you to set a value for a pseudo column unless it is a table column. The value of this connection setting is of the format "Table1=Column1, Table1=Column2, Table2=Column3". You can use the "*" character to include all tables and all columns; for example, "*=*".

The timezone by which the server's Edm.DateTime values are represented. The value of this property will affect how Edm.DateTime filters and results are converted between the server and the client machine.

Remarks

By default, Edm.DateTime values in the server will be assumed to be GMT. If the server is known to represent such values in a specific timezone, then the abbreviation of that timezone can be provided here (i.e. EST). From there, the driver will convert any Edm.DateTime derived filters from the installed machine's local timezone to the one specified for the server. Conversely, similar values returned by the OData server will be converted from the specified timezone to the installed machine's local timezone before being exposed in the result set.

A boolean indicating if we should list stored procedures which return a collection of entities as views.

Remarks

A boolean indicating if we should list stored procedures which return a collection of entities as views.

Whether you need to specify the base entity's key to query navigation property views.

Remarks

This connection property is primarily used with limited OData APIs; it determines whether navigation properties can be retrieved from the base entity set. In OData, navigation properties link a base entity to a related entity or a collection of related entitites.

For more on navigation properties, see Data Model.

Working with Limited APIs

In OData, the $expand parameter is used to expand specified navigation properties when requesting data from a given entity set. In SQL, this makes it possible to execute a SELECT * to a navigation property view.

If $expand is not supported, a different request must be made to retrieve a navigation property, one that specifies the primary key of the base entity set. This API restriction is reflected in SQL: You will need to specify the base entity's primary key in the WHERE clause.

For example, consider two entities with a one-to-many relationship in the Northwind sample service, Categories and Products. In OData, the Products associated with a given Category could be represented as a navigation property on the base Category entity set. The Sync App models the Products navigation property as a Categories_Products view.

If $expand is not supported, use a query like the following to this view:

SELECT       * 
FROM         Categories_Products
WHERE        (Categories_CategoryID = 1)

A boolean indicating if the odata service supports server side formulas.

Remarks

OData has a number of server side formulas that are built into the specifications. However, many services do not natively support them and will return errors when these formulas are appended to the $filter parameter. These formulas can be used to make some queries that use them execute much faster. If your OData service supports formulas, change this connection property to true. Otherwise, leave it as false.

The value in seconds until the timeout error is thrown, canceling the operation.

Remarks

If Timeout = 0, operations do not time out. The operations run until they complete successfully or until they encounter an error condition.

If Timeout expires and the operation is not yet complete, the Sync App throws an exception.

Whether or not the CData ADO.NET Provider for OData should use client side paging.

Remarks

Some sources do not support server side paging. In these cases, set UseClientSidePaging to true. Otherwise, leave it as false. Setting UseClientSidePaging to true on a source that already supports paging can cause incomplete results.

Whether or not the OData source uses Etags.

Remarks

Some OData sources do not use Etags. In these instances, set UseEtags to False.

A filepath pointing to the JSON configuration file containing your custom views.

Remarks

User Defined Views are defined in a JSON-formatted configuration file called UserDefinedViews.json. The Sync App automatically detects the views specified in this file.

You can also have multiple view definitions and control them using the UserDefinedViews connection property. When you use this property, only the specified views are seen by the Sync App.

This User Defined View configuration file is formatted as follows:

• Each root element defines the name of a view.
• Each root element contains a child element, called query, which contains the custom SQL query for the view.

For example:

{
	"MyView": {
		"query": "SELECT * FROM Lead WHERE MyColumn = 'value'"
	},
	"MyView2": {
		"query": "SELECT * FROM MyTable WHERE Id IN (1,2,3)"
	}
}

"UserDefinedViews", "C:\\Users\\yourusername\\Desktop\\tmp\\UserDefinedViews.json"

Boolean determining if simple names should be used for tables and columns.

Remarks

OData tables and columns can use special characters in names that are normally not allowed in standard databases. UseSimpleNames makes the Sync App easier to use with traditional database tools.

Setting UseSimpleNames to true will simplify the names of tables and columns returned. It will enforce a naming scheme such that only alphanumeric characters and the underscore are valid for the displayed table and column names. Any nonalphanumeric characters will be converted to an underscore.