TIBCO Data Virtualization OData Adapter Guide

Two-Second Adva

TIBCO Data Virtualization®

OData Adapter GuideVersion 8.3

Last Updated: April 30, 2020

ntage®

Important Information SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER

PURPOSE.

USE OF TIBCO SOFTWARE AND THIS DOCUMENTATION IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENTATION IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME.

This document is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc.

TIBCO and the TIBCO logo are either registered trademarks or trademarks of TIBCO Software Inc. in the United

States and/or other countries

TIBCO, Two-Second Advantage, TIBCO Spotfire, TIBCO ActiveSpaces, TIBCO Spotfire Developer, TIBCO EMS,

TIBCO Spotfire Automation Services, TIBCO Enterprise Runtime for R, TIBCO Spotfire Server, TIBCO Spotfire

Web Player, TIBCO Spotfire Statistics Services, S-PLUS, and TIBCO Spotfire S+ are either registered trademarks

or trademarks of TIBCO Software Inc. in the United States and/or other countries.

All other product and company names and marks mentioned in this document are the property of their

respective owners and are mentioned for identification purposes only.

THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.

THIS DOCUMENTATION IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS DOCUMENTATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENTATION. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENTATION AT ANY TIME.

THE CONTENTS OF THIS DOCUMENTATION MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.

Copyright © 2002-2020 TIBCO Software Inc. ALL RIGHTS RESERVED.

TIBCO Software Inc. Confidential Information

TIBCO® Data Virtualization

Contents | 1

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2

Product-Specific Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2How to Access TIBCO Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3How to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3How to Join TIBCO Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

TDV OData Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5

Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Deploying the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Connecting to OData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Basic Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Advanced Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Connection String Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Using OAuth Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Creating a Custom OAuth App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Custom Credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Headless Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Advanced Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

SQL Compliance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51SELECT Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52SELECT INTO Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58INSERT Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58UPDATE Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59DELETE Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60EXECUTE Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Stored Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Data Type Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

|2

Preface

For information on the following, see the TDV User Guide:

• Adding a Data Source

• Introspecting a Data Source

• Testing the Connection to Your Data Source

Documentation for this and other TIBCO products is available on the TIBCO Documentation site. This site is updated more frequently than any documentation that might be included with the product. To ensure that you are accessing the latest available help topics, please visit:

• https://docs.tibco.com

Product-Specific Documentation

The following documents form the TIBCO® Data Virtualization(TDV) documentation set:

• Users

TDV Getting Started Guide

TDV User Guide

TDV Client Interfaces Guide

TDV Tutorial Guide

TDV Northbay Example

• Administration

TDV Installation and Upgrade Guide

TDV Administration Guide

TDV Active Cluster Guide

TDV Security Features Guide

TDV Monitor Guide

• Data Sources

TDV Adapter Guides

TDV Data Source Toolkit Guide (Formerly Extensibility Guide)


https://docs.tibco.com

Preface |3

• References

TDV Reference Guide

TDV Application Programming Interface Guide

• Other

TDV Business Directory Guide

TDV Discovery Guide

• TIBCO TDV and Business Directory Release Notes Read the release notes for a list of new and changed features. This document also contains lists of known issues and closed issues for this release.

How to Access TIBCO Documentation

Documentation for TIBCO products is available on the TIBCO Product Documentation website mainly in the HTML and PDF formats.

The TIBCO Product Documentation website is updated frequently and is more current than any other documentation included with the product. To access the latest documentation, visit https://docs.tibco.com.

Documentation for TIBCO Data Virtualization is available on https://docs.tibco.com/products/tibco-data-virtualization-server.

How to Contact TIBCO Support

You can contact TIBCO Support in the following ways:

• For an overview of TIBCO Support, visit https://www.tibco.com/services/support.

• For accessing the Support Knowledge Base and getting personalized content about products you are interested in, visit the TIBCO Support portal at https://support.tibco.com.

• For creating a Support case, you must have a valid maintenance or support contract with TIBCO. You also need a user name and password to log in to https://support.tibco.com. If you do not have a user name, you can request one by clicking Register on the website.


https://docs.tibco.com

https://docs.tibco.com/products/tibco-data-virtualization-server

https://www.tibco.com/services/support

https://support.tibco.com

https://support.tibco.com

4 | Preface

How to Join TIBCO Community

TIBCO Community is the official channel for TIBCO customers, partners, and employee subject matter experts to share and access their collective experience. TIBCO Community offers access to Q&A forums, product wikis, and best practices. It also offers access to extensions, adapters, solution accelerators, and tools that extend and enable customers to gain full value from TIBCO products. In addition, users can submit and vote on feature requests from within the TIBCO Ideas Portal. For a free registration, go to https://community.tibco.com.


https://ideas.tibco.com/

https://ideas.tibco.com/

https://community.tibco.com

|5

TDV OData Adapter

OData Version Support

The adapter is a standard OData consumer that can read and write to OData 2.0, 3.0, and 4.0 services. The major authentication schemes are supported, including HTTP Basic, Digest, and NTLM, as well as SSL/TLS. The adapter also facilitates connecting to data sources that use the OAuth authentication standard.

Requirements and Restrictions

The Supported SQL section shows the SQL syntax supported by the adapter and points out any limitations.

Getting Started

Deploying the Adapter

For instructions on deploying the adapter, refer to the Installation Guide, section Installing the Advanced Adapters.

Connecting to OData

Basic Tab shows how to authenticate to OData and configure any necessary connection properties. Additional adapter capabilities can be configured using the available Connection properties on the Advanced tab. The Advanced Settings section shows how to set up more advanced configurations and troubleshoot connection errors.

Basic Tab

Connecting to OData

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


6 | Basic Tab

Fine-Tuning Data Access

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

NavigationPropertiesAsViews: By default, the adapter 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 adapter uses the default format defined by the service.

ODataVersion: Use this to override the version detected by the adapter. This is useful if your application supports an older OData version.

UseIdUrl: By default the adapter 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.

Authenticating to OData

The adapter supports the major authentication schemes, including HTTP and Windows.

Set AuthScheme to use the following authentication types.

The adapter simplifies OAuth configuration. See Using OAuth Authentication for a how-to.

HTTP Authentication

The adapter supports authentication with HTTP Basic, Digest, and custom headers. To use Basic or Digest, set the User and Password. You can specify other authentication values in CustomHeaders.

Windows (NTLM)

Set the Windows User and Password to connect and set AuthScheme to "NTLM".

Kerberos and Kerberos Delegation


l

Advanced Tab |7

To authenticate with Kerberos, set AuthScheme to NEGOTIATE. To use Kerberos Delegation, set AuthScheme to KERBEROSDELEGATION. If needed, provide the User, Password, and KerberosSPN. By default, the adapter attempts to communicate with the SPN at the specified Url.

Securing OData Connections

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

Advanced Tab

The connection string properties describe the various options that can be used to establish a connection.

Connection String Options

The following is the full list of the options you can configure in the connection string for this provider.

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

Azure AD Resource

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

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

Callback URL The OAuth callback URL to return to when authenticating. This value must match the callback URL you specify in your app settings.

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

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

Custom Headers Other headers as determined by the user (optional).


8 | Advanced Tab

Custom Url Params

The custom query string to be included in the request.

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

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

Firewall Port The TCP port for a proxy-based firewall.

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

Firewall Type The protocol used by a proxy-based firewall.

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

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

Kerberos SPN The service principal name for the Kerberos domain controller.

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

Navigation Properties As Views

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

OAuth Access Token

The access token for connecting using OAuth.

OAuth Access Token Secret

The OAuth access token secret for connecting using OAuth.

OAuth Access Token URL

The URL to retrieve the OAuth access token from.

OAuth Authorization URL

The authorization URL for the OAuth service.

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

OAuth Client Secret

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

OAuth Grant Type The grant type for the OAuth flow. Can be either CLIENT, CODE or PASSWORD.


Advanced Tab |9

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

OAuth Refresh Token

The OAuth refresh token for the corresponding OAuth access token.

OAuth Refresh Token URL

The URL to refresh the OAuth token from.

OAuth Request Token URL

The URL the service provides to retrieve request tokens from. Required in OAuth 1.0.

OAuth Settings Location

The location of the settings file where OAuth values are saved when InitiateOAuth is set to GETANDREFRESH or REFRESH.

OAuth Verifier The verifier code returned from the OAuth authorization URL.

OAuth Version The version of OAuth being used. Enter 1.0 or 2.0.

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

Other The other parameters necessary to connect to a data source, such as username and password, when applicable.

Pagesize The maximum number of results to return per page from OData when UseClientSidePaging is true.

Password The password used to authenticate to the OData site.

Proxy Auth Scheme

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

Proxy Auto Detect This indicates whether to use the system proxy settings or not. Set ProxyAutoDetect to FALSE to use custom proxy settings. This takes precedence over other proxy settings.

Proxy Exceptions A semicolon separated list of hosts or IPs that will be exempt from connecting through the ProxyServer .

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

Proxy Port The TCP port the ProxyServer proxy is running on.

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

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


10 | Advanced Tab

Auth Scheme

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

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

Readonly You can use this property to enforce read-only access to OData from the provider.

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

SSL Client Cert Password

The password for the TLS/SSL client certificate.

SSL Client Cert Subject

The subject of the TLS/SSL client certificate.

SSL Client Cert Type

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

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

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

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

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

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

Use Client Side Paging

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

Use Etags Whether or not the OData source uses Etags.

User The user who is authenticating to the OData site.

Use Simple Names Whether or not to use simple names for tables and columns.


Advanced Tab |11

Data Type

string

Default Value

"NONE"

Remarks

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

NTLM: Set this to use your Windows credentials for 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 adapter will negotiate an authentication mechanism with the server. Set AuthScheme to NEGOTIATE if you want to use Kerberos authentication.

KERBEROSDELEGATION: Set this to use delegation through the Kerberos protocol. Set the User and Password of the account you want to impersonate.

SHAREPOINTONLINE: Set this to use SharePoint Online authentication.

Azure AD Resource

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

Data Type

string

Default Value

""

Remarks

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


12 | Advanced Tab

Azure AD Tenant

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

Data Type

string

Default Value

"common"

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.

Callback URL

The OAuth callback URL to return to when authenticating. This value must match the callback URL you specify in your app settings.

Data Type

string

Default Value

""

Remarks

During the authentication process, the OAuth authorization server redirects the user to this URL. This value must match the callback URL you specify in your app settings.

Continue On Error

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


Advanced Tab |13

Data Type

bool

Default Value

false

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.

Cookies

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

Data Type

string

Default Value

""

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 OData Adapter, they can be manually specified here. Specify cookies in name=value pairs separated by a semicolon. For instance: Cookie1=value;Cookie2=value2.

Custom Headers

Other headers as determined by the user (optional).

Data Type

string


14 | Advanced Tab

Default Value

""

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, etc.

The headers must be of the format "header: value" as described in the HTTP specifications. Header lines should be separated by CRLF (the carriage return and line feed 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 adapter to integrate with specialized or nonstandard APIs.

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, etc.

The headers must be of the format "header: value" as described in the HTTP specifications. Header lines should be separated by CRLF (the carriage return and line feed 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 adapter to integrate with specialized or nonstandard APIs.

Custom Url Params

The custom query string to be included in the request.

Data Type

string

Default Value

""


Advanced Tab |15

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, etc. The values in the query string must be URL encoded.

Data Format

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

Data Type

string

Default Value

""

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.

Firewall Password

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

Data Type

string

Default Value

""

Remarks

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

Firewall Port

The TCP port for a proxy-based firewall.


16 | Advanced Tab

Data Type

string

Default Value

""

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.

Firewall Server

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

Data Type

string

Default Value

""

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 adapter uses the system proxy by default. To use a different proxy, set ProxyAutoDetect to false.

Firewall Type

The protocol used by a proxy-based firewall.

Data Type

string


Advanced Tab |17

Default Value

"NONE"

Remarks

This property specifies the protocol that the adapter will use to tunnel traffic through the FirewallServer proxy. Note that by default the adapter 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.

Firewall User

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

Data Type

string

Default Value

""

Type Default Port

Description

TUNNEL

80 When this is set, the adapter opens a connection to OData and traffic flows back and forth through the proxy.

SOCKS4 1080 When this is set, the adapter sends data through the SOCKS 4 proxy specified by FirewallServer and FirewallPort and passes the FirewallUser value to the proxy, which determines if the connection request should be granted.

SOCKS5 1080 When this is set, the adapter sends data through the SOCKS 5 proxy specified by FirewallServer and FirewallPort. If your proxy requires authentication, set FirewallUser and FirewallPassword to credentials the proxy recognizes.


18 | Advanced Tab

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.

Initiate OAuth

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

Data Type

string

Default Value

"OFF"

Remarks

The following options are available:

OFF: Indicates that the OAuth flow will be handled entirely by the user. An OAuthAccessToken will be required to authenticate.

GETANDREFRESH: Indicates that the entire OAuth Flow will be handled by the adapter. 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.

REFRESH: Indicates that the adapter will only handle refreshing the OAuthAccessToken. The user will never be prompted by the adapter to authenticate via the browser. The user must handle obtaining the OAuthAccessToken and OAuthRefreshToken initially.

Kerberos SPN

The service principal name for the Kerberos domain controller.

Data Type

string

Default Value

""


Advanced Tab |19

Remarks

If the service principal name on the Kerberos domain controller is not the same as the URL that you are authenticating to, the service principal name should be set here.

Location

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

Data Type

string

Default Value

""

Remarks

The path to a directory which contains the schema files for the adapter (.rsd files for tables and views, .rsb files for stored procedures). The Location property is only needed if you would like to customize definitions (e.g., change a column name, ignore a column, etc.) or extend the data model with new tables, views, or stored procedures.

The schema files are deployed alongside the adapter assemblies. You must also ensure that Location points to the folder that contains the schema files. The folder location can be a relative path from the location of the executable.

Navigation Properties As Views

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

Data Type

bool

Default Value

true


20 | Advanced Tab

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.

OAuth Access Token

The access token for connecting using OAuth.

Data Type

string

Default Value

""

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 username and password. The access token protects your credentials by keeping them on the server.

OAuth Access Token Secret

The OAuth access token secret for connecting using OAuth.


Advanced Tab |21

Data Type

string

Default Value

""

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.

OAuth Access Token URL

The URL to retrieve the OAuth access token from.

Data Type

string

Default Value

""

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.

OAuth Authorization URL

The authorization URL for the OAuth service.

Data Type

string

Default Value

""


22 | Advanced Tab

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.

OAuth Client Id

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

Data Type

string

Default Value

""

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.

OAuth Client Secret

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

Data Type

string

Default Value

""

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.


Advanced Tab |23

OAuth Grant Type

The grant type for the OAuth flow. Can be either CLIENT, CODE or PASSWORD.

Data Type

string

Default Value

"CODE"

Remarks

The grant type for the OAuth flow. Can be either CLIENT, CODE or PASSWORD.

OAuth Params

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

Data Type

string

Default Value

""

Remarks

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

OAuth Refresh Token

The OAuth refresh token for the corresponding OAuth access token.

Data Type

string

Default Value

""


24 | Advanced Tab

Remarks

The OAuthRefreshToken property is used to refresh the OAuthAccessToken when using OAuth authentication.

OAuth Refresh Token URL

The URL to refresh the OAuth token from.

Data Type

string

Default Value

""

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.

OAuth Request Token URL

The URL the service provides to retrieve request tokens from. Required in OAuth 1.0.

Data Type

string

Default Value

""

Remarks

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


Advanced Tab |25

OAuth Settings Location

The location of the settings file where OAuth values are saved when InitiateOAuth is set to GETANDREFRESH or REFRESH.

Data Type

string

Default Value

"%APPDATA%\\CData\\OData Data Provider\\OAuthSettings.txt"

Remarks

When InitiateOAuth is set to GETANDREFRESH or REFRESH, the adapter saves OAuth values to avoid requiring the user to manually enter OAuth connection properties and allowing the credentials to be shared across connections or processes.

Alternatively to specifying a file path, memory storage can be used instead. Memory locations are specified by using a value starting with 'memory://' followed by a unique identifier for that set of credentials (ex: memory://user1). The identifier can be anything you choose but should be unique to the user. Unlike with the file based storage, you must manually store the credentials when closing the connection with memory storage to be able to set them in the connection when the process is started again. The OAuth property values can be retrieved with a query to the sys_connection_props system table. If there are multiple connections using the same credentials, the properties should be read from the last connection to be closed.

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

OAuth Verifier

The verifier code returned from the OAuth authorization URL.

Platform %APPDATA%

Windows The value of the APPDATA environment variable

Mac ~/Library/Application Support

Linux ~/.config


26 | Advanced Tab

Data Type

string

Default Value

""

Remarks

The verifier code returned from the OAuth authorization URL. This can be used on systems where a browser cannot be launched such as headless systems.

Authentication on Headless Machines

Set OAuth Settings Location along with OAuthVerifier. When you connect, the adapter exchanges the OAuthVerifier for the OAuth authentication tokens and saves them, encrypted, to the specified file. Set InitiateOAuth to GETANDREFRESH automate the exchange.

Once the OAuth settings file has been generated, you can remove OAuthVerifier from the connection properties and connect with OAuthSettingsLocation set.

To automatically refresh the OAuth token values, set OAuthSettingsLocation and additionally set InitiateOAuth to REFRESH.

OAuth Version

The version of OAuth being used. Enter 1.0 or 2.0.

Data Type

string

Default Value

""

Remarks

The version of OAuth being used. Enter 1.0 or 2.0.

OData Version

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


Advanced Tab |27

Data Type

string

Default Value

"AUTO"

Remarks

The version of OData to use. By default the adapter 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.

Other

Hidden properties needed only in specific use cases.

Data Type

string

Default Value

""

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

DefaultColumnSize Sets the default length of string fields when the data source does not provide column length in the metadata. The default value is 2000.

ConvertDateTimeToGMT Whether to convert date-time values to GMT, instead of the local time of the machine.

RecordToFile=filename Records the underlying socket data transfer to the specified file.


28 | Advanced Tab

Pagesize

The maximum number of results to return per page from OData when UseClientSidePaging is true.

Data Type

string

Default Value

"1000"

Remarks

The Pagesize property affects the maximum number of results to return per page from OData when Use Client Side Paging is true. It will do nothing if when Use Client Side Paging is false. A higher value will return more results per page, but may also cause a timeout exception. If you must use client paging on your server and have a fast server, setting a higher Pagesize may be desireable. We recommend testing various sizes with Use Client Side Paging against a large resultset to determine what works best in your use case

Password

The password used to authenticate to the OData site.

Data Type

string

Default Value

""

Remarks

The password used to authenticate to the OData site.

Proxy Auth Scheme

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


Advanced Tab |29

Data Type

string

Default Value

"BASIC"

Remarks

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

Note that the adapter 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 adapter performs HTTP BASIC authentication.

DIGEST: The adapter performs HTTP DIGEST authentication.

NEGOTIATE: The adapter retrieves an NTLM or Kerberos token based on the applicable protocol for authentication.

PROPRIETARY: The adapter 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 Firewall Type.

Proxy Auto Detect

This indicates whether to use the system proxy settings or not. Set ProxyAutoDetect to FALSE to use custom proxy settings. This takes precedence over other proxy settings.

Data Type

bool

Default Value

true


30 | Advanced Tab

Remarks

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

NOTE: When this property is set to True, the proxy used is determined as follows:

• A search from the JVM properties (http.proxy, https.proxy, socksProxy, etc.) is performed.

• In the case that the JVM properties don't exist, a search from java.home/lib/net.properties is performed.

• In the case that java.net.useSystemProxies is set to True, a search from the SystemProxy is performed.

• In Windows only, an attempt is made to retrieve these properties from the Internet Options in the registry.

To connect to an HTTP proxy, see Proxy Server. For other proxies, such as SOCKS or tunneling, see Firewall Type.

Proxy Exceptions

A semicolon separated list of hosts or IPs that will be exempt from connecting through the ProxyServer .

Data Type

string

Default Value

""

Remarks

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

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

Proxy Password

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


Advanced Tab |31

Data Type

string

Default Value

""

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 Firewall Type.

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

Proxy Port

The TCP port the ProxyServer proxy is running on.

Data Type

string

Default Value

"80"

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 Firewall Type.


32 | Advanced Tab

Proxy Server

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

Data Type

string

Default Value

""

Remarks

The hostname or IP address of a proxy to route HTTP traffic through. The adapter 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 Firewall Type.

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

Proxy SSL Type

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

Data Type

string

Default Value

"AUTO"

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:

AUTO Default setting. If the URL is an HTTPS URL, the adapter will use the TUNNEL option. If the URL is an HTTP URL, the component will use the NEVER option.


Advanced Tab |33

Proxy User

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

Data Type

string

Default Value

""

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 username of a user recognized by the HTTP proxy. If you are using Windows or Kerberos authentication, set this property to a username in one of the following formats: user@domaindomain\user

Readonly

You can use this property to enforce read-only access to OData from the provider.

Data Type

bool

Default Value

false

ALWAYS

The connection is always SSL enabled.

NEVER The connection is not SSL enabled.

TUNNEL The connection is through a tunneling proxy: The proxy server opens a connection to the remote host and traffic flows back and forth through the proxy.


34 | Advanced Tab

Remarks

If this property is set to true, the adapter will allow only SELECT queries. INSERT, UPDATE, DELETE, and stored procedure queries will cause an error to be thrown.

SSL Client Cert

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

Data Type

string

Default Value

""

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. Please refer to the SSL Client Cert Subject field for details.

Designations of certificate stores are platform-dependent.

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

MY A certificate store holding personal certificates with their associated private keys.

CA Certifying authority certificates.

ROOT

Root certificates.

SPC Software publisher certificates.


Advanced Tab |35

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 (i.e. PKCS12 certificate store).

SSL Client Cert Password

The password for the TLS/SSL client certificate.

Data Type

string

Default Value

""

Remarks

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

SSL Client Cert Subject

The subject of the TLS/SSL client certificate.

Data Type

string

Default Value

"*"

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.


36 | Advanced Tab

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

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

SSL Client Cert Type

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

Data Type

string

Default Value

""

Remarks

This property can take one of the following values:

Field Meaning

CN Common Name. This is commonly a host name like www.server.com.

O Organization

OU Organizational Unit

L Locality

S State

C Country

E Email Address


Advanced Tab |37

USER - default For Windows, this specifies that the certificate store is a certificate store owned by the current user. Note: This store type is not available in Java.

MACHINE For Windows, this specifies that the certificate store is a machine store. Note: this store type is not available in Java.

PFXFILE The certificate store is the name of a PFX (PKCS12) file containing certificates.

PFXBLOB The certificate store is a string (base-64-encoded) representing a certificate store in PFX (PKCS12) format.

JKSFILE The certificate store is the name of a Java key store (JKS) file containing certificates. Note: this store type is only available in Java.

JKSBLOB The certificate store is a string (base-64-encoded) representing a certificate store in Java key store (JKS) format. Note: this store type is only available in Java.

PEMKEY_FILE The certificate store is the name of a PEM-encoded file that contains a private key and an optional certificate.

PEMKEY_BLOB The certificate store is a string (base64-encoded) that contains a private key and an optional certificate.

PUBLIC_KEY_FILE The certificate store is the name of a file that contains a PEM- or DER-encoded public key certificate.

PUBLIC_KEY_BLOB The certificate store is a string (base-64-encoded) that contains a PEM- or DER-encoded public key certificate.

SSHPUBLIC_KEY_FILE The certificate store is the name of a file that contains an SSH-style public key.

SSHPUBLIC_KEY_BLOB The certificate store is a string (base-64-encoded) that contains an SSH-style public key.

P7BFILE The certificate store is the name of a PKCS7 file containing certificates.

PPKFILE The certificate store is the name of a file that contains a PPK (PuTTY Private Key).


38 | Advanced Tab

SSL Server Cert

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

Data Type

string

Default Value

""

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 will be rejected.

This property can take the forms:

XMLFILE The certificate store is the name of a file that contains a certificate in XML format.

XMLBLOB The certificate store is a string that contains a certificate in XML format.

Description Example

A full PEM Certificate (example shortened for brevity)

-----BEGIN CERTIFICATE----- MIIChTCCAe4CAQAwDQYJKoZIhv......Qw== -----END CERTIFICATE-----

A path to a local file containing the certificate C:\cert.cer

The public key (example shortened for brevity) -----BEGIN RSA PUBLIC KEY----- MIGfMA0GCSq......AQAB -----END RSA PUBLIC KEY-----

The MD5 Thumbprint (hex values can also be either space or colon separated)

ecadbdda5a1529c58a1e9e09828d70e4

The SHA1 Thumbprint (hex values can also be either space or colon separated)

34a929226ae0819f2ec14b4a3d904f801cbb150d


Advanced Tab |39

If not specified, any certificate trusted by the machine will be accepted. Use '*' to signify to accept all certificates (not recommended for security concerns).

Supports Expand

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

Data Type

bool

Default Value

true

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 adapter 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


40 | Advanced Tab

WHERE (Categories_CategoryID = 1)

Supports Formulas

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

Data Type

bool

Default Value

false

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 throw 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

Timeout

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

Data Type

string

Default Value

"60"

Remarks

If the Timeout property is set to 0, operations do not time out: They run until they complete successfully or encounter an error condition.

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


Advanced Tab |41

Url

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

Data Type

string

Default Value

""

Remarks

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

Use Client Side Paging

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

Data Type

bool

Default Value

false

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.

Use Etags

Whether or not the OData source uses Etags.

Data Type

bool


42 | Advanced Tab

Default Value

false

Remarks

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

User

The user who is authenticating to the OData site.

Data Type

string

Default Value

""

Remarks

The user who is authenticating to the OData site.

Use Simple Names

Whether or not to use simple names for tables and columns.

Data Type

bool

Default Value

false

Remarks

This connection property controls whether simple names will be used for tables and columns. This means that tables and columns will be output as alphanumeric. Underscores will be used to replace any unconventional characters for a SQL identifier such such as commas, colons, spaces, etc.


Logging |43

Logging

The adapter uses log4j to generate log files. The settings within the log4j configuration file will be used by the adapter to determine the type of messages to log. The following categories can be specified:

Error: Only error messages will be logged.

Info: Both Error and Info messages will be logged.

Debug: Error, Info, and Debug messages will be logged.

The Other property of the adapter can be used to set Verbosity to specify the amount of detail to be included in the log file, i.e. Verbosity=4;

You can use Verbosity to specify the amount of detail to include in the log within a category. The following verbosity levels are mapped to the log4j categories:

0 = Error

1-2 = Info

3-5 = Debug

For example, if the log4j category is set to DEBUG, the Verbosity option can be set to 3 for the minimum amount of debug information or 5 for the maximum amount of debug information.

Note that the log4j settings override the Verbosity level specified. The adapter will never log at a Verbosity level greater than what is configured in the log4j properties. In addition, if Verbosity is set to a level less than the log4j category configured, Verbosity will default to the minimum value for that particular category. For example, if Verbosity is set to a value less than three and the Debug category is specified, the Verbosity will default to 3.

Here is a breakdown of the Verbosity levels and the information that they log:

1 - Will log the query, the number of rows returned by it, the start of execution and the time taken, and any errors.

2 - Will log everything included in Verbosity 1 and HTTP headers.

3 - Will additionally log the body of the HTTP requests.

4 - Will additionally log transport-level communication with the data source. This includes SSL negotiation.

5 - Will additionally log communication with the data source and additional details that may be helpful in troubleshooting problems. This includes interface commands.


44 | Using OAuth Authentication

Configure Logging for the OData Adapter

By default, logging is turned on without debugging. If debugging information is desired, the following line from the TDV Server's log4j.properties file can be uncommented (default location of this file is: C:\Program Files\TIBCO\TDV Server <version>\conf\server). log4j.logger.com.cdata=DEBUG

The TDV Server will need to be restarted after changing the log4j.properties file, which can be accomplished by running the composite.bat script located at C:\Program Files\TIBCO\TDV Server <version>\conf\server. Note reauthenticating to the TDV Studio will be required after restarting the server.

An example of the calls would be: .\composite.bat monitor restart

All logs for the adapter will be written to the "cs_cdata.log" file as specified in the log4j properties.

Note the "log4j.logger.com.cdata=DEBUG" option is not required if the "Debug Output Enabled" option is set to true within the TDV Studio. To accomplish this, navigate to Administrator -> Configuration to display the configuration window. Then expand Server -> Configuration -> Debugging and set the Debug Output Enabled option to True.

Using OAuth Authentication

OAuth requires the authenticating user to interact with OData using the browser. Most OData services will not require OAuth. This section is only for OData endpoints that require OAuth. The adapter facilitates this in various ways as described below.

Required OAuth Connection Properties

There are several required connection properties to establish an OAuth connection. These must be obtained from the API documentation of the OData service you are connecting to.

• OAuthVersion: The version of OAuth being used. Enter 1.0 or 2.0.

• OAuthAccessTokenURL: The URL to retrieve the OAuth access token from.

• OAuthAuthorizationURL: The URL that needs to be opened in the browser for the user to grant permissions.


Using OAuth Authentication |45

• OAuthRefreshTokenURL: The URL to use when refreshing an expired access token.

• OAuthRequestTokenURL: The URL the service provides to retrieve request tokens from. Required in OAuth 1.0.

• OAuthGrantType: The grant type for the OAuth flow. Can be either CLIENT, CODE or PASSWORD.

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

Creating a Custom OAuth App

In addition to the previously mentioned connection properties, you will need to register an app to obtain the OAuthClientId and OAuthClientSecret. See Creating a Custom OAuth App for information on creating a custom app.

Creating a Custom OAuth App

Creating a custom application in most services requires registering as a developer and creating an app in the UI of the service. This is not necessarily true for all services. In some you must contact the serive provider to create the app for you. However it is done, you must obtain the values for OAuthClientId, OAuthClientSecret, and CallbackURL.

Obtain OAuth URLs

You will need the following URLs to complete the OAuth interaction. These URLs are often obtained from the API reference for your data source.

• OAuthRequestTokenURL: Required for OAuth 1.0. In OAuth 1.0 this is the URL where the app makes a request for the request token.

• OAuthAuthorizationURL: Required for OAuth 1.0 and 2.0. This is the URL where the user logs into the service and grants permissions to the application. In OAuth 1.0 if permissions are granted the request token is authorized.

• OAuthAccessTokenURL: Required for OAuth 1.0 and 2.0. This is the URL where the request for the access token is made. In OAuth 1.0 the authorized request token is exchanged for the access token.

• OAuthRefreshTokenURL: Required for OAuth 2.0. In OAuth 2.0 this is the URL where the refresh token is exchanged for a new access token when the old one expires. Note that for your data source this may be the same as the access token URL.



• CallbackURL: Required depending on your data source; your data source may require you to define this URL when you create an app. This is the URL you want to be used as a trusted redirect URL (also called a callback URL), where the user will return with the token that verifies that they have granted your app access.

Note that your data source may require the port.

Set Additional Azure AD OAuth Properties

In addition to the OAuth URLs and the following properties, set AzureADResource and AzureADTenant when authenticating to Azure AD OAuth endpoints.

Authenticate to OData

After setting the required URLs and the following connection properties you are ready to connect:

• OAuthVersion: Set this to 1.0 or 2.0.

• OAuthGrantType: By default, the adapter negotiates the browser-login flow. This is the "CODE" grant type. However, OAuth 2.0 also supports an exchange of login credentials for the access token; to use this grant type, set this property to "PASSWORD".

• InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the access token in the connection string.

• OAuthClientId: Set this to the client Id in your app settings. This is also called the consumer key.

• OAuthClientSecret: Set this to the client secret in your app settings. This is also called the consumer secret.

• OAuthParams: Set this to a comma-separated list of any additional parameters required by your data source.

• CallbackURL: Set this to the localhost callback url you would like to use for a response from the OAuthAuthorizationURL. We recommend using http://localhost:33333 if possible.


Using OAuth Authentication |47

Custom Credentials

Desktop Authentication with your OAuth App

Follow the steps below to authenticate with the credentials for a custom OAuth app. See Creating a Custom OAuth App.

Get an OAuth Access Token

After setting the following, you are ready to connect:

• OAuthClientId: Set this to the Client Id in your app settings.

• OAuthClientSecret: Set this to the Client Secret in your app settings.

• CallbackURL: Set this to the Redirect URL in your app settings.

• InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken. .

When you connect the adapter opens the OAuth endpoint in your default browser. Log in and grant permissions to the application. The adapter then completes the OAuth process:

1. Extracts the access token from the callback URL and authenticates requests.

2. Obtains a new access token when the old one expires.

3. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

Headless Machines

Using OAuth on a Headless Machine

To create OData data sources on headless servers or other machines on which the adapter cannot open a browser, you need to authenticate from another machine. Authentication is a two-step process.

1. Instead of installing the adapter on another machine, you can follow the steps below to obtain the OAuthVerifier value. Or, you can install the adapter on another machine and transfer the OAuth authentication values, after you authenticate through the usual browser-based flow.

2. You can then configure the adapter to automatically refresh the access token from the headless machine.



You can follow the headless OAuth authentication flow using the adapter's embedded OAuth credentials or using the OAuth credentials for your custom OAuth app.

Using the Credentials for a Custom OAuth App

Create a Custom OAuth App

See Creating a Custom OAuth App for a procedure. You can then follow the procedures below to authenticate and connect to data.

Obtain a Verifier Code

Set the following properties on the headless machine:

• InitiateOAuth: Set this to OFF.

• OAuthClientId: Set this to the App Id in your app settings.

• OAuthClientSecret: Set this to the App Secret in your app settings.

You can then follow the steps below to authenticate from another machine and obtain the OAuthVerifier connection property.

1. Call the GetOAuthAuthorizationUrl stored procedure with the CallbackURL input parameter set to the exact Redirect URI you specified in your app settings.

2. Open the returned URL in a browser. Log in and grant permissions to the adapter. You are then redirected to the callback URL, which contains the verifier code.

3. Save the value of the verifier code. You will set this in the OAuthVerifier connection property.

On the headless machine, set the following connection properties to obtain the OAuth authentication values:

• OAuthClientId: Set this to the consumer key in your app settings.

• OAuthClientSecret: Set this to the consumer secret in your app settings.

• OAuthVerifier: Set this to the verifier code.

• OAuthSettingsLocation: Set this to persist the encrypted OAuth authentication values to the specified file.

• InitiateOAuth: Set this to REFRESH.

Connect to Data

After the OAuth settings file is generated, set the following properties to connect to data:


Advanced Settings |49

• OAuthSettingsLocation: Set this to the file containing the encrypted OAuth authentication values. Make sure this file gives read and write permissions to the provider to enable the automatic refreshing of the access token.


Transfer OAuth Settings

Follow the steps below to install the adapter on another machine, authenticate, and then transfer the resulting OAuth values.

On a second machine, install the adapter and connect with the following properties set:

• OAuthSettingsLocation: Set this to a writable text file.

• InitiateOAuth: Set this to GETANDREFRESH.

• OAuthClientId: Set this to the Client Id in your app settings.

• OAuthClientSecret: Set this to the Client Secret in your app settings.

• CallbackURL: Set this to the Callback URL in your app settings.

Test the connection to authenticate. The resulting authentication values are written, encrypted, to the path specified by OAuthSettingsLocation. Once you have successfully tested the connection, copy the OAuth settings file to your headless machine. On the headless machine, set the following connection properties to connect to data:


• OAuthSettingsLocation: Set this to the path to your OAuth settings file. Make sure this file gives read and write permissions to the adapter to enable the automatic refreshing of the access token.

Advanced Settings

Customizing the SSL Configuration

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

Connecting Through a Firewall or Proxy

HTTP Proxies


50 | Advanced Settings

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.

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 and in addition set the following.

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

To connect to other proxies, set FirewallType, FirewallServer, and FirewallPort. To tunnel the connection, set FirewallType to TUNNEL. To authenticate to a SOCKS proxy, set FirewallType to SOCKS5. Additionally, specify FirewallUser and FirewallPassword.

Troubleshooting the Connection

To show adapter activity from query execution to network traffic, use Logfile and Verbosity. The examples of common connection errors below show how to use these properties to get more context. Contact the support team for help tracing the source of an error or circumventing a performance issue.

Authentication errors: Typically, recording a Logfile at Verbosity 4 is necessary to get full details on an authentication error.

Queries time out: A server that takes too long to respond will exceed the adapter's client-side timeout. Often, setting the Timeout property to a higher value will avoid a connection error. Another option is to disable the timeout by setting the property to 0. Setting Verbosity to 2 will show where the time is being spent.

The certificate presented by the server cannot be validated: This error indicates that the adapter cannot validate the server's certificate through the chain of trust. (If you are using a self-signed certificate, there is only one certificate in the chain.)


SQL Compliance |51

To resolve this error, you must verify yourself that the certificate can be trusted and specify to the adapter that you trust the certificate. One way you can specify that you trust a certificate is to add the certificate to the trusted system store; another is to set SSLServerCert.

SQL Compliance

The OData Adapter supports several operations on data, including querying, deleting, modifying, and inserting.

SELECT Statements

See SELECT Statements for a syntax reference and examples.

See Data Model for information on the capabilities of the OData API.

INSERT Statements

See INSERT Statements for a syntax reference and examples, as well as retrieving the new records' Ids.

UPDATE Statements

The primary key Id is required to update a record. See UPDATE Statements for a syntax reference and examples.

DELETE Statements

The primary key Id is required to delete a record. See DELETE Statements for a syntax reference and examples.

EXECUTE Statements

Use EXECUTE or EXEC statements to execute stored procedures. See EXECUTE Statements for a syntax reference and examples.

Names and Quoting

Table and column names are considered identifier names; as such, they are restricted to the following characters: [A-Za-z0-9_:@].

To use a table or column name with characters not listed above, the name must be quoted using double quotes ("name") in any SQL statement.


52 | SQL Compliance

Strings must be quoted using single quotes (e.g., 'John Doe').

Transactions and Batching

Transactions are not currently supported.

Additionally, the adapter does not support batching of SQL statements. To execute multiple commands, you can create multiple instances and execute each separately. Or, use Batch Processing.

SELECT Statements

A SELECT statement can consist of the following basic clauses.

SELECT

INTO

FROM

JOIN

WHERE

GROUP BY

HAVING

UNION

ORDER BY

LIMIT

SELECT Syntax

The following syntax diagram outlines the syntax supported by the OData adapter: SELECT { [ TOP <numeric_literal> ] { * | { <expression> [ [ AS ] <column_reference> ] | { <table_name> | <correlation_name> } .* } [ , ... ] } [ INTO csv:// [ filename= ] <file_path> [ ;delimiter=tab ] ] { FROM <table_reference> [ [ AS ] <identifier> ] }


SQL Compliance |53

[ WHERE <search_condition> ] [ ORDER BY { <column_reference> [ ASC | DESC ] } [ , ... ] ] [ LIMIT <expression> [ { OFFSET | , } <expression> ] ] } | SCOPE_IDENTITY()

<expression> ::= | <column_reference> | @ <parameter> | ? | COUNT( * | { <expression> } ) | { AVG | MAX | MIN | SUM | COUNT } ( <expression> ) | <literal> | <sql_function>

<search_condition> ::= { <expression> { = | != | > | < | >= | <= | IS NULL | IS NOT NULL | LIKE | AND | OR } [ <expression> ] } [ { AND | OR } ... ]

Examples

Return all columns: SELECT * FROM Lead

Rename a column: SELECT "FullName" AS MY_FullName FROM Lead

Search data: SELECT * FROM Lead WHERE FirstName <> 'Bartholomew';

The OData APIs support the following operators in the WHERE clause: =, !=, >, <, >=, <=, IS NULL, IS NOT NULL, LIKE, AND, OR. SELECT * FROM Lead WHERE FirstName <> 'Bartholomew';

Return the number of items matching the query criteria: SELECT COUNT(*) AS MyCount FROM Lead

Sort a result set in ascending order: SELECT Id, FullName FROM Lead ORDER BY FullName ASC


54 | SQL Compliance

Predicate Functions

CEILING(value)

Returns the value rounded up to the nearest whole number (no decimal component).

expression: The value to round.

CONCAT(string_expr1, string_expr2)

Returns the string that is the concatenation of string_expr1 and string_expr2.

string_expr1: The first string to be concatenated.

string_expr2: The second string to be concatenated.

CONTAINS(string_expression, string_search)

Returns true if string_expression contains string_expression, otherwise returns false.

string_expression: The string expression to search within.

string_search: The value to search for.

DATE(datetime_offset)

Returns the current date using the specified datetime_offset.

datetime_offset: The datetime offset to use when retrieving the current date.

DAY(datetime_date)

Returns the integer that specifies the day component of the specified date.

datetime_date: The datetime string that specifies the date.

ENDSWITH(string_expression, string_suffix)

Returns true if string_expression ends with string_suffix, otherwise returns false.


string_suffix: The string suffix to search for.


SQL Compliance |55

FLOOR(value)

Returns the value rounded down to the nearest whole number (no decimal component).

value: The value to round.

FRACTIONALSECONDS(datetime_time)

Returns the decimal value that specifies the fractional seconds component of the specified time.

datetime_time: The datetime string that specifies the time.

HOUR(datetime_time)

Returns the integer that specifies the hour component of the specified time.


INDEXOF(string_expression, string_search)

Returns the index location where string_search is contained within string_expression.


string_search: The search value to locate within string_expression.

ISOF(string_expression, string_type)

Returns true if the string_expression is assignable to type string_type, otherwise returns false.

string_expression: The string expression to check the type of.

string_type: The name of the type.

LENGTH(string_expression)

Returns the number of characters of the specified string expression.

string_expression: The string expression.

MAXDATETIME()

Returns the latest possible datetime.


56 | SQL Compliance

MINDATETIME()

Returns the earliest possible datetime.

MINUTE(datetime_time)

Returns the integer that specifies the minute component of the specified time.


MONTH(datetime_date)

Returns the integer that specifies the month component of the specified date.


NOW()

Returns the current datetime.

REPLACE(string_expression, string_search, string_replace)

Returns the string after replacing any found string_search values with string_replace.

string_expression: The string expression to perform a replace on.

string_search: The string value to find within string_expression.

string_replace: The string value replace and string_search instances found.

ROUND(value)

Returns the value to the nearest whole number (no decimal component).

value: The value to round.

SECOND(datetime_time)

Returns the integer that specifies the second component of the specified time.


STARTSWITH(string_expression, string_prefix)

Returns true if string_expression starts with string_prefix, otherwise returns false.


string_prefix: The string prefix to search for.


SQL Compliance |57

SUBSTRING(string_expression, integer_start [,integer_length])

Returns the part of the string with the specified length; starts at the specified index.

expression: The character string.

start: The positive integer that specifies the start index of characters to return.

length: The positive integer that specifies how many characters will be returned.

SUBSTRINGOF(string_expression, string_search)

Returns true if string_expression contains string_expression, otherwise returns false.


string_search: The value to search for.

TIME(datetime_offset)

Returns the current time using datetime_offset.

datetime_offset: The datetime offset.

TOLOWER(string_expression)

Returns the string_expression with the uppercase character data converted to lowercase.

string_expression: The string expression to lowercase.

TOTALOFFSETMINUTES(datetime_date)

Returns the integer that specifies the offset minutes component of the specified date.


TOTALSECONDS(duration)

Returns the duration value in total seconds.

string_duration: The duration.

TOUPPER(string_expression)

Returns the string_expression with the lowercase character data converted to uppercase.


58 | SQL Compliance

string_expression: The string expression to uppercase.

TRIM(string_expression)

Returns the string_expression with the leading and trailing whitespace removed.

string_expression: The string expression to trim.

YEAR(datetime_date)

Returns the integer that specifies the year component of the specified date.


SELECT INTO Statements

You can use the SELECT INTO statement to export formatted data to a file.

Data Export with an SQL Query

The following query exports data into a file formatted in comma-separated values (CSV): SELECT Id, FullName INTO "csv://Lead.txt" FROM "Lead" WHERE FirstName = 'Bartholomew'

You can specify other formats in the file URI. The possible delimiters are tab, semicolon, and comma with the default being comma. The following example exports tab-separated values: SELECT Id, FullName INTO "csv://Lead.txt;delimiter=tab" FROM "Lead" WHERE FirstName = 'Bartholomew'

INSERT Statements

To create new records, use INSERT statements.

INSERT Syntax

The INSERT statement specifies the columns to be inserted and the new column values. You can specify the column values in a comma-separated list in the VALUES clause: INSERT INTO <table_name> ( <column_reference> [ , ... ] )VALUES ( { <expression> | NULL } [ , ... ] )


SQL Compliance |59

<expression> ::= | @ <parameter> | ? | <literal>

You can use the executeUpdate method of the Statement and PreparedStatement classes to execute data manipulation commands and retrieve the rows affected. To retrieve the Id of the last inserted record use getGeneratedKeys. Additionally, set the RETURN_GENERATED_KEYS flag of the Statement class when you call prepareStatement. String cmd = "INSERT INTO Lead (FullName) VALUES (?)";PreparedStatement pstmt = connection.prepareStatement(cmd,Statement.RETURN_GENERATED_KEYS);pstmt.setString(1, "John");int count = pstmt.executeUpdate();System.out.println(count+" rows were affected");ResultSet rs = pstmt.getGeneratedKeys();while(rs.next()){ System.out.println(rs.getString("Id"));}connection.close();

UPDATE Statements

To modify existing records, use UPDATE statements.

Update Syntax

The UPDATE statement takes as input a comma-separated list of columns and new column values as name-value pairs in the SET clause. UPDATE <table_name> SET { <column_reference> = <expression> } [ , ... ] WHERE { Id = <expression> } [ { AND | OR } ... ]


You can use the executeUpdate method of the Statement or PreparedStatement classes to execute data manipulation commands and retrieve the rows affected. String cmd = "UPDATE Lead SET FullName='John' WHERE Id = ?";PreparedStatement pstmt = connection.prepareStatement(cmd);pstmt.setString(1, "1045625d-99ee-e011-a272-00155d01ad6b");int count = pstmt.executeUpdate();System.out.println(count + " rows were affected");connection.close();


60 | SQL Compliance

DELETE Statements

To delete from a table, use DELETE statements.

DELETE Syntax

The DELETE statement requires the table name in the FROM clause and the row's primary key in the WHERE clause. <delete_statement> ::= DELETE FROM <table_name> WHERE { Id = <expression> } [ { AND | OR } ... ]


You can use the executeUpdate method of the Statement or PreparedStatement classes to execute data manipulation commands and retrieve the number of affected rows. Connection connection = DriverManager.getConnection("jdbc:odata:User=myuseraccount;Password=mypassword;URL=http://myserver/myOrgRoot;",);String cmd = "DELETE FROM Lead WHERE Id = ?";PreparedStatement pstmt = connection.prepareStatement(cmd);pstmt.setString(1, "1045625d-99ee-e011-a272-00155d01ad6b");int count=pstmt.executeUpdate();connection.close();

EXECUTE Statements

To execute stored procedures, you can use EXECUTE or EXEC statements. EXEC and EXECUTE assign stored procedure inputs, referenced by name, to values or parameter names.

Stored Procedure Syntax

To execute a stored procedure as an SQL statement, use the following syntax: { EXECUTE | EXEC } <stored_proc_name> { [ @ ] <input_name> = <expression>} [ , ... ]



Data Model |61

Example Statements

Reference stored procedure inputs by name: EXECUTE my_proc @second = 2, @first = 1, @third = 3;

Execute a parameterized stored procedure statement: EXECUTE my_proc second = @p1, first = @p2, third = @p3;

Data Model

The OData Adapter 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 adapter 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 adapter 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.

Tables

The adapter 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.


62 | Data Model

Executing Deep Inserts with SQL

The adapter 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 create a temporary table for the navigation property and then reference the temporary table in the insert to the base table. Reference the temporary table in the appropriate navigation property column on the base table. Each navigation property column is prefixed with the word "Linked".

Note that you must define the temporary tables and insert to the base entity within the same connection.

Example: Deep Inserts in Northwind

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 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)


Data Model |63

The OData Adapter 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 OData Adapter 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')

Code Example

Below is the complete code to create the new Order:

Connection conn = DriverManager.getConnection("jdbc:odata:URL=http://services.odata.org/Northwind/Northwind.svc;");

Statement stat = conn.createStatement();

stat.executeUpdate("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')");

stat.executeUpdate("INSERT INTO Order_Details#TEMP (ProductID, UnitPrice, Quantity, Discount) VALUES (72, 34.80, 5, 0)");

stat.executeUpdate("INSERT INTO Order_Details#TEMP (ProductID, UnitPrice, Quantity, Discount) VALUES (42, 9.80, 10, 0)");

stat.executeUpdate("INSERT INTO Employees#TEMP (EmployeeID) VALUES (5)");


64 | Data Model

stat.executeUpdate("INSERT INTO Shippers#TEMP (ShipperID) VALUES (3)");

stat.executeUpdate("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')");

stat.close();

Views

Modeling Navigation Properties

By default, the adapter 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 OData Adapter 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.

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.


Data Model |65

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 adapter supports OData deep inserts. See Tables for more information on specifying navigation properties when you create an entity.

Stored Procedures

Stored procedures are available to complement the data available from the Data Model. It may be necessary to update data available from a view using a stored procedure because the data does not provide for direct, table-like, two-way updates. In these situations, the retrieval of the data is done using the appropriate view or table, while the update is done by calling a stored procedure. Stored procedures take a list of parameters and return back a dataset that contains the collection of tuples that constitute the response.

OData Adapter Stored Procedures

Name Description

CreateAssociation Creates an association between two entities based on a navigation property.


66 | Data Model

CreateAssociation

Creates an association between two entities based on a navigation property.

Input

GetOAuthAccessToken

Gets the auth token used to authenticate to the service.

GetOAuthAuthorizationUrl

Gets an authorization URL from the data source. The authorization URL can be used to generate a verifier required to obtain the OAuth token.

GetSAPCSRFToken

Returns a CSRF token and cookie for authentication to SAP.

ListAssociations Lists associations for a given table and navigation property.

ListNavigationProperties

Lists navigation properties for a given table and the tables they are associated with. Navigation properties are used by the Association stored procedures.

RefreshOAuthAccessToken

Obtains an updated OAuthAccessToken if passed a token to refresh.

RemoveAssociation

Removes an association between two entities based on a navigation property.

Search Searches OData using the given URL.

Name Type Description

FromId String The Id of the entity you are creating an associations for.

FromTable String The table where the entity comes from that you are creating an association for. For example, if the FromId was from a table called Customers, set this parameter to: Customers.

ToNavigationProperty

String The navigation property you are creating an association on. It can be obtained from ListNavigationProperties.

ToId String The id of the navigation entity. This will come from the table associated with the navigation property.


Data Model |67

GetOAuthAccessToken

Gets the auth token used to authenticate to the service.

Input

HttpMethod String An override for the http method to use when creating the association in case the OData source being used does not follow the specifications.


AuthMode String The type of authentication you are attempting. Use App for a Windows application, or Web for Web-based applications.

The default value is APP.

Verifier String A verifier returned by the service that must be input to return the access token. Needed only when using the Web auth mode. Obtained by navigating to the URL returned in GetOAuthAuthorizationUrl.

CallbackUrl String The URL the user will be redirected to after authorizing your application.

Other_Options String Other options to control behavior of OAuth.

Cert String Path for a personal certificate .pfx file. Only available for OAuth 1.0.

Cert_Password String Personal certificate password. Only available for OAuth 1.0.

AuthToken String The request token returned by navigating to the URL returned by OAuthGetUserAuthorizationURL. Available only for OAuth 1.0.

Sign_Method String The request secret key returned by OAuthGetUserAuthorizationURL. Available only for OAuth 1.0.


68 | Data Model

Result Set Columns

GetOAuthAuthorizationUrl

Gets an authorization URL from the data source. The authorization URL can be used to generate a verifier required to obtain the OAuth token.

Input

GrantType String The signature method used to calculate the signature for OAuth 1.0.

The allowed values are HMAC-SHA1, PLAINTEXT.

The default value is HMAC-SHA1.

Post_Data String Authorization grant type. Only available for OAuth 2.0.

The post data to submit, if any.

OAuthParam String Other parameters may be defined in the format 'param:paramname'.


OAuthAccessToken String The OAuth access token.

OAuthAccessTokenSecret

String The OAuth access token secret.

* String Other outputs that may be returned by the data source.


CallbackURL String The URL the user will be redirected to after authorizing your application.

Other_Options String Other options to control the behavior of OAuth.

Cert String Path for a personal certificate .pfx file. Only available for OAuth 1.0.


Data Model |69

Result Set Columns

GetSAPCSRFToken

Returns a CSRF token and cookie for authentication to SAP.

Input

Cert_Password String Personal certificate password. Only available for OAuth 1.0.

Sign_Method String The signature method used to calculate the signature for OAuth 1.0.

The allowed values are HMAC-SHA1, PLAINTEXT.

The default value is HMAC-SHA1.

OAuthParam:* String Other parameters may be defined in the format 'param:paramname'.


AuthToken String The authorization token, passed into the GetOAuthAccessToken stored procedure.

AuthSecret String The authorization secret token, passed into the GetOAuthAccessToken stored procedure.

URL String The authorization URL. This URL will need to be navigated to so that the user can authorize your application to have access. A verifier may be returned when the CallbackURL is redirected to, which will be used in GetOAuthAccessToken.

* String Other outputs that may be returned by the data source.


URL String The base URL of the SAP OData service.

TokenHeader String The name of the HTTP header for the SAP CSRF token.

The default value is x-csrf-token.


70 | Data Model

Result Set Columns

ListAssociations

Lists associations for a given table and navigation property.

Input

Result Set Columns

ListNavigationProperties

Lists navigation properties for a given table and the tables they are associated with. Navigation properties are used by the Association stored procedures.


Success String Whether or not the request was successful.

CSRFToken String The Cross-Site Request Forgery token to be set in the header for subsequent requests.

Cookie String The SAP cookie to be set in the header for subsequent requests.


FromId String The Id of the entity you are listing associations for.

FromTable String The table where the entity comes from that you are listing entities for. For example, if the FromId was from a table called Customers, set this parameter to: Customers.

NavigationProperty String The navigation property you are listing assications for. It can be obtained from ListNavigationProperties.


Uri String The linked url.


Data Model |71

Input

Result Set Columns

RefreshOAuthAccessToken

Obtains an updated OAuthAccessToken if passed a token to refresh.

Input

Result Set Columns

RemoveAssociation

Removes an association between two entities based on a navigation property.


TableName String The name of the table to list navigation properties for.


Name String The name of the navigation property.

AssociatedTable String The table the navigation property is associated with.


OAuthRefreshToken String The refresh token returned from the original authorization code exchange.


OAuthAccessToken String The new OAuthAccessToken returned from the service.

OAuthAccessTokenSecret

String The new OAuthAccessTokenSecret returned from the service.

OAuthRefreshToken String A token that may be used to obtain a new access token.

ExpiresIn String The remaining lifetime on the access token.


72 | Data Type Mapping

Input

Search

Searches OData using the given URL.

Input

Result Set Columns

Data Type Mapping

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


FromId String The Id of the entity you are removing an associations for.

FromTable String The table where the entity comes from that you are removing an association for. For example, if the FromId was from a table called Customers, set this parameter to: Customers.

ToNavigationProperty

String The navigation property you are removing an association on. It can be obtained from ListNavigationProperties.

ToId String The id of the navigation entity. This will come from the table associated with the navigation property.


Url String Full URL to use while searching OData.


* String Output will vary for each entity.

OData V2 OData V3 OData V4 CData Schema


Data Type Mapping |73

Edm.Binary Edm.Binary Edm.Binary binary

Edm.Boolean Edm.Boolean Edm.Boolean bool

Edm.DateTime Edm.DateTime Edm.DateTimeOffset datetime

Edm.Decimal Edm.Decimal Edm.Decimal decimal

Edm.Double Edm.Double Edm.Double double

Edm.Guid Edm.Guid Edm.Guid guid

Edm.Int32 Edm.Int32 Edm.Int32 int

Edm.String Edm.String Edm.String string

Edm.Time Edm.Time Edm.TimeOfDay time


74 | Data Type Mapping


TIBCO Data Virtualization OData Adapter Guide

Documents